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:
|
1 2 3 4 5 |
var queryRequest = new QueryRequest() .Statement("SELECT * FROM `beer-sample` LIMIT $1") .AddPositionalParameter(10) .Timeout(new TimeSpan(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:
|
1 2 3 4 5 6 7 8 9 |
var result = await bucket.QueryAsync<dynamic>(queryRequest); if(result.Success) { foreach(var doc in result.Rows) { Console.Writeline(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:
|
1 2 3 4 5 6 |
var queryRequest = new QueryRequest() .Statement("SELECT * FROM `beer-sample` LIMIT 1") .AdHoc(false); var result = bucket.Query<dynamic>(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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
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 } } } |
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:
|
1 2 3 4 5 6 |
function (doc) { if (doc.type == "brewery" && doc.geo.lon && doc.geo.lat) { emit({ "type": "Point", "coordinates": [doc.geo.lon, doc.geo.lat]}, null); } } |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
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); } } |
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.
