Couchbase .NET SDK 2.2.0 now Available!

Hoje estamos lançando a versão 2.2.0 do Couchbase .NET SDK. O foco principal dessa versão é a compatibilidade de recursos com o Couchbase Server 4.0 GA, que também foi lançado hoje! Os principais recursos dessa versão são:

Suporte a N1QL
Suporte a escalonamento multidimensional (MDS)
Durabilidade aprimorada
Visualizações espaciais GEO

Juntamente com esses recursos principais, o SDK 2.2.0 também contém várias correções de bugs e aprimoramentos. Se estiver usando uma versão anterior do SDK, é altamente recomendável que você atualize para essa versão mais recente.

As notas de versão completas estão disponíveis aqui.

N1QL: Uma nova linguagem de consulta semelhante ao SQL para JSON

Sem dúvida, o recurso mais importante lançado com o Couchbase Server 4.0 é o suporte completo para consulta de documentos JSON com N1QL, uma nova linguagem de consulta semelhante à SQL para documentos. A versão 2.2.0 do Couchbase .NET SDK oferece suporte total ao N1QL por meio de uma nova API de cliente.

A classe QueryRequest

A classe QueryRequest representa uma solicitação de consulta N1QL para o Couchbase Server. Ela encapsula a API REST do N1QL na porta 8093 e fornece uma interface segura para a execução de consultas. Juntamente com o cliente de consulta interno incorporado à classe CouchbaseBucket, ela lida com grande parte do encanamento e da complexidade da API REST, por exemplo:

Lógica de repetição de falhas temporárias e recuperáveis
Distribuição uniforme de consultas em todo o cluster
Lógica para lidar com declarações preparadas
Cache de Uri
Mapeamento dos resultados da consulta para POCOs
e outros

A classe QueryRequest separa a instrução N1QL real da execução, do tratamento de erros e do mapeamento de dados dos resultados da consulta. Aqui está um exemplo de uso da QueryRequest para criar uma solicitação que será executada posteriormente no CouchbaseBucket:

var queryRequest = new QueryRequest()
    .Statement("SELECT * FROM `beer-sample` LIMIT $1")
    .AddPositionalParameter(10)
    .Timeout(new TimeSpan(0, 0, 0, 500));

var queryRequest = novo Solicitação de consulta()

.Declaração("SELECT * FROM `beer-sample` LIMIT $1")

.AddPositionalParameter(10)

.Tempo limite(novo Tempo(0, 0, 0, 500));

Primeiro, criamos o objeto QueryRequest e passamos uma instrução N1QL para ele. Em seguida, adicionamos um parâmetro posicional (observe que também há suporte para parâmetros de nomes). Por fim, substituímos o valor global ClientConfiguration.QueryRequestTimeout por um tempo limite personalizado de 500 milissegundos.

Quando tivermos criado um QueryRequest, poderemos executá-lo em um CouchbaseBucket usando o método Query:

var result = await bucket.QueryAsync<dynamic>(queryRequest);
if(result.Success)
{
    foreach(var doc in result.Rows)
    {
        Console.Writeline(doc);
    }
}

var resultado = aguardar balde.QueryAsync<dinâmico>(queryRequest);

se(resultado.Sucesso)

{

antes de(var doc em resultado.Fileiras)

{

Console.Linha de escrita(doc);

}

É isso! A nova API tem os seguintes métodos e propriedades expostos por QueryRequest:

Método	Descrição	Opcional
Declaração	Define uma instrução N1QL a ser executada.	falso
Preparado	Define um comando N1QL a ser executado de forma otimizada usando o queryPlan fornecido.	verdadeiro
Tempo limite	Define o tempo máximo a ser gasto com a solicitação.	verdadeiro
Somente leitura	Se for uma solicitação GET, isso sempre será verdadeiro, caso contrário, será falso.	verdadeiro
Métricas	Especifica que as métricas devem ser retornadas com os resultados da consulta.	verdadeiro
AddNamedParameter	Adiciona um parâmetro nomeado aos parâmetros do comando ou comando preparado.	verdadeiro
AddPositionalParameters	Adiciona um parâmetro posicional aos parâmetros do comando ou comando preparado.	verdadeiro
Consistência de varredura	Especifica a garantia/restrição de consistência para a varredura de índices.	verdadeiro
AddHoc	Se for definido como false, o cliente tentará executar otimizações de forma transparente com base nos recursos do servidor, como preparar a instrução e, em seguida, executar um plano de consulta em vez da consulta bruta.	verdadeiro

Esses são os parâmetros pragmáticos e totalmente compatíveis. Além disso, há parâmetros/métodos para Compression, Format e Encoding, mas não sugiro que sejam usados no momento. Além disso, ScanConsistency de AtPlus e StatementPlus não são suportados no momento e lançarão uma NotSupportedException se forem passados.

A classe QueryResult

Depois que uma solicitação tiver sido enviada ao servidor e processada, uma resposta será devolvida ao cliente na forma de um documento JSON. O cliente pegará a resposta e a mapeará para a classe QueryRequest. O cliente também analisará os códigos de status da resposta (tanto N1QL quanto HTTP) e determinará se a solicitação deve ser tentada novamente ou não. Em geral, qualquer erro HTTP 400 não será repetido, ele será devolvido ao chamador porque indica um problema do cliente.

As propriedades e os métodos importantes da classe QueryRequest são os seguintes:

Método	Descrição
Sucesso	True se a consulta foi bem-sucedida.
Mensagem	Mensagem opcional retornada pelo mecanismo de consulta ou pelo cliente
Exceção	Se Success for falso e uma exceção tiver sido capturada internamente, esse campo conterá a exceção.
RequestId	Obtém o identificador da solicitação.
ClientContextId	Obtém o clientContextID da solicitação, se tiver sido fornecido. Usado para depuração.
Assinatura	Obtém o esquema dos resultados. Presente somente quando a consulta é concluída com êxito.
Fileiras	Obtém uma lista de todos os objetos retornados pela consulta. Um objeto pode ser qualquer valor JSON.
Status	Obtém o status da solicitação; os valores possíveis são: sucesso, em execução, erros, concluído, parado, tempo limite, fatal.
Erros	Obtém uma lista de 0 ou mais objetos de erro; se ocorrer um erro durante o processamento da solicitação, ele será representado por um objeto de erro nessa lista.
Avisos	Obtém uma lista de 0 ou mais objetos de aviso; se um aviso ocorreu durante o processamento da solicitação, ele será representado por um objeto de aviso nessa lista.
Métricas	Obtém um objeto que contém métricas sobre a solicitação.
HttpStatusCode	Obtém o código de status HTTP da solicitação.

O campo Success geralmente é usado para indicar o sucesso/falha de uma solicitação de consulta e, se ela falhar, os campos Errors, Warnings, Status e HttpStatusCode podem ser usados para diagnosticar o erro/problema para que ele possa ser resolvido.

Uso de demonstrações preparadas

Cada instrução executada pelo servidor deve ter um plano de consulta associado criado, o que consome tempo e recursos. Os comandos preparados permitem que o plano de consulta gerado seja reutilizado várias vezes, melhorando o desempenho geral e a integridade do servidor. Para usar instruções preparadas, o parâmetro AdHoc deve ser definido como false:

 var queryRequest = new QueryRequest()
        .Statement("SELECT * FROM `beer-sample` LIMIT 1")
        .AdHoc(false);

 var result = bucket.Query<dynamic>(queryRequest);

var queryRequest = novo Solicitação de consulta()

.Declaração("SELECT * FROM `beer-sample` LIMIT 1")

.AdHoc(falso);

var resultado = balde.Consulta<dinâmico>(queryRequest);

O SDK cuidará da preparação, do armazenamento em cache e da reutilização do extrato preparado para esse extrato e para todas as solicitações futuras com ele.

Dimensionamento multidimensional

Também conhecido como MDS, o dimensionamento multidimensional é um novo recurso do Couchbase Server 4.0 que permite atribuir os serviços que você deseja executar em um nó específico do cluster. Por exemplo, se você tiver um cluster de quatro nós, um nó pode ser dedicado a consultas, um nó dedicado à indexação e dois nós dedicados ao serviço de dados - ou alguns serviços combinados podem ser executados em um nó específico. O próprio SDK sabe quais nós suportam os respectivos serviços e encaminhará consultas e chaves para o nó correto no cluster de forma "automática"

Durabilidade aprimorada

A durabilidade aprimorada é uma nova maneira de impor restrições de durabilidade. As restrições de durabilidade são restrições que você coloca em uma mutação para garantir que uma chave tenha sido replicada e/ou persistida em "n" réplicas. A grande diferença entre as restrições de durabilidade mais antigas baseadas em "observar" é que a durabilidade aprimorada usa um número de sequência de réplica para determinar se uma chave atingiu a capacidade desejada, enquanto a "observar" compara o estado da réplica da própria chave.

A durabilidade aprimorada não é uma alteração nas APIs de chave/valor existentes, mas é simplesmente uma alteração de configuração; o restante é feito "sob o capô" pelas APIs internas dos SDKs:

var config = new ClientConfiguration
{
    BucketConfigs = new Dictionary<string, BucketConfiguration>
    {
        {
            "default", new BucketConfiguration
            {
                UseEnhancedDurability = true
            }
        }
    }
};
using (var cluster = new Cluster(config))
{
    using (var bucket = cluster.OpenBucket())
    {
        var result = bucket.Insert(key, "foo", ReplicateTo.Two, PersistTo.Two);
        if(result.Success)
        {
            //do stuff if successful
        }
    }
}

var configuração = novo Configuração de cliente

{

BaldeConfigs = novo Dicionário<string, BucketConfiguration>

{

"default", novo BucketConfiguration

{

UseEnhancedDurability = verdadeiro

}

};

usando (var agrupamento = novo Aglomerado(configuração))

{

usando (var balde = agrupamento.OpenBucket())

{

var resultado = balde.Inserir(chave, "foo", ReplicarPara.Dois, PersistTo.Dois);

se(resultado.Sucesso)

{

//fazer coisas se for bem-sucedido

}

A chave aqui é que UseEnhancedDurability foi definido como true na BucketConfiguration para o bucket "padrão". A API de durabilidade externa é a mesma; os campos PersistTo e ReplicateTo são passados junto com a chave e o valor com a durabilidade desejada que deve ser atendida antes do retorno da operação.

Visualizações espaciais GEO

Uma nova reviravolta em um antigo servidor Couchbase é o suporte a visualizações espaciais GEO. As visualizações espaciais GEO são criadas pela definição de funções Map usando JavaScript (não há suporte para redução) que permitem consultar intervalos geográficos.

Aqui está um exemplo de uma visualização espacial:

function (doc) { 
  if (doc.type == "brewery" && doc.geo.lon && doc.geo.lat) {
        emit({ "type": "Point", "coordinates": [doc.geo.lon, doc.geo.lat]}, null);
  }
}

função (doc) {

se (doc.tipo == "cervejaria" && doc.geo.solitário && doc.geo.lat) {

emitir({ "tipo": "Ponto", "coordenadas": [doc.geo.solitário, doc.geo.lat]}, nulo);

}

A API do SDK para uso de visualizações espaciais é muito semelhante à API de visualização, mas usa uma classe SpatialViewQuery especial para construir um objeto que é enviado à classe CouchbaseBucket para execução.

 var query = new SpatialViewQuery().From("beer_ext_spatial", "points")
         .Stale(StaleState.False)
         .StartRange(-10.37109375, 33.578014746143985)
         .EndRange(43.76953125, 71.9653876991313)
         .ConnectionTimeout(60000)
         .Limit(1)
         .Skip(0);

 var result = bucket.Query<dynamic>(query);
 if(result.Success)
 {
    foreach(var row in result.Rows)
    {
        Console.Writeline(row);
    }
 }

var consulta = novo Pesquisa de visualização espacial().De("beer_ext_spatial", "pontos")

.Vencido(StaleState.Falso)

.StartRange(-10.37109375, 33.578014746143985)

.EndRange(43.76953125, 71.9653876991313)

.ConnectionTimeout(60000)

.Limite(1)

.Pular(0);

var resultado = balde.Consulta<dinâmico>(consulta);

se(resultado.Sucesso)

{

antes de(var fila em resultado.Fileiras)

{

Console.Linha de escrita(fila);

}

Você pode saber mais sobre como escrever visualizações espaciais aqui.

Como obtê-lo

O SDK está disponível para download diretamente, por meio do NuGet, ou clonando e extraindo o repositório do Github:

Faça o download dos binários aqui.
O pacote NuGet pode ser encontrado aqui.
O repositório do Github é aqui.

Jeff Morris, engenheiro de software sênior, Couchbase

Compartilhe este artigo

Platform

Self-Managed

Services

Capabilities

Why Couchbase?

Migrate to Capella

By Use Case

By Industry

By Application Need

Popular Docs

By Developer Role

Quickstart

Resource Center

About

Partnerships

Our Services

Partners: Register a Deal

Ready to register a deal with Couchbase?

Marriott

O Couchbase .NET SDK 2.2.0 já está disponível!

N1QL: Uma nova linguagem de consulta semelhante ao SQL para JSON

A classe QueryRequest

A classe QueryResult

Uso de demonstrações preparadas

Dimensionamento multidimensional

Durabilidade aprimorada

Visualizações espaciais GEO

Como obtê-lo

Receba atualizações do blog do Couchbase em sua caixa de entrada

Autor

Postado por Jeff Morris, engenheiro de software sênior, Couchbase

Deixe um comentário Cancelar resposta

Pronto para começar a usar o Couchbase Capella?

Iniciar a construção

Use o Capella gratuitamente

Entre em contato