Prévia do suporte a N1QL DP4 para o Couchbase .NET SDK 2.0!

Ontem, a equipe de consulta aqui no Couchbase lançou o tão esperado N1QL Developer Preview 4! Se você ainda não ouviu falar do N1QL, trata-se de uma nova linguagem de consulta semelhante ao SQL que o Couchbase está desenvolvendo para consultar armazenamentos de dados não relacionais como o Couchbase. O objetivo é trazer a familiaridade do SQL para o mundo flexível e sem esquema do JSON. Hoje estamos lançando uma "prévia" do suporte ao N1QL DP4 fornecido pelo Couchbase .NET SDK 2.0.

O que isso significa é que estamos fornecendo uma versão de pré-lançamento, não testada e não executada em produção do SDK que inclui grande parte da funcionalidade fornecida pelo N1QL DP4! Deixe-me dizer isso mais uma vez: NÃO USE EM PRODUÇÃO!!!! Agora que a polícia da diversão já teve sua paz e estragou a festa, vamos ver o que há no N1QL DP4 e o que é suportado atualmente por essa versão prévia do SDK!

O que há no N1QL Developer Preview 4?

O N1QL DP4 se baseia no excelente trabalho realizado no DP 1-3, fornecendo a sintaxe e a linguagem de elementos N1QL completas. Além disso, ele fornece subconsultas, suporte experimental para construções de linguagem de manipulação de dados (DML) como INSERT, UPDATE, UPSERT e DELETE e, o que é mais importante para o SDK, uma API REST totalmente nova!

A API REST passou por uma grande reforma e está muito mais próxima de estar pronta para o horário nobre. Uma lista parcial dos recursos suportados pela nova API REST inclui:

• Suporte a declarações preparadas (como o cache do plano de consulta)
• Parâmetros posicionais e nomeados
• Uma API de erros aprimorada e mais robusta
• Métricas de consulta
• Tempo limite de consulta

Por fim, a documentação foi reformulada e atualizada e pode ser encontrada em aqui.

Instalação do DP4

Infelizmente, embora o N1QL DP4 esteja quase completamente integrado ao Couchbase Server, ele ainda não foi empacotado com ele. Isso significa que, para usar o DP4, você terá que fazer o download dos bits, iniciar o serviço e associá-lo a uma instância do Couchbase Server. Felizmente, fazer isso é relativamente fácil:

• Primeiro, faça o download do N1QL DP4 aqui.
• Em seguida, descompacte-o em um diretório em seu disco rígido
• Por fim, execute o seguinte comando para iniciar o serviço e associá-lo a uma instância do Couchbase Server: .cbq-engine -datastore=https://[server_name]:8091/

Depois de fazer isso (é claro, altere [nome do servidor] para que seja um IP da instância do Couchbase), você precisará criar um índice para cada bucket que deseja usar. Para fazer isso, você pode executar a ferramenta de linha de comando de consulta interativa e criar os índices usando-a, ou pode fazer download do Couchbase .NET 2.0 SDK com N1QL DP4 "preview". Mostrarei primeiro como fazer isso com o shell interativo e, mais tarde, mostrarei como fazer isso programaticamente com o SDK.

• Navegue até o diretório onde você descompactou o N1QL DP4 e digite o seguinte, alterando o com sua instância do servidor Couchbase: .cbq -engine=https://:8093/
• Em seguida, digite o seguinte: CREATE PRIMARY INDEX ON [bucket name]
• Pressione Enter (observe para alterar [bucket name] para um nome de bucket válido em sua instância do servidor Couchbase.

Usarei o bucket de amostra "beer sample" que vem pré-instalado com o Couchbase mais tarde, portanto, você provavelmente deve fazer o mesmo se quiser acompanhar o processo. Depois de fazer o download e instalar o N1QL DP4, podemos usar o Couchbase .NET SDK 2.0 para criar índices e executar consultas.

Uso do SDK com o N1QL DP4

Para usar o SDK, você precisará do Visual Studio instalado junto com o .NET Framework 4.5 ou superior. Se estiver usando o Mono, não o testei, mas você também poderá acompanhar o processo, desde que esteja usando uma versão do Mono que seja funcionalmente equivalente ao .NET Framework 4.5. Especificamente, o suporte para async/await, a palavra-chave dynamic e algumas das novas bibliotecas do .NET.

Download e referência dos bits

Para começar a trabalhar rapidamente com o SDK, siga estas etapas:

• A versão prévia especial do SDK pode ser encontrada em aqui. Faça o download e descompacte-o em algum lugar de seu disco rígido.
• Abra o VS e crie um novo projeto de "Aplicativo de console", chame-o de N1QL-DP4-Preview ou o que preferir.
• Clique com o botão direito do mouse na pasta de referências no "Solution Explorer" à direita e depois em "Add Reference"
• Use o botão "browse" para localizar as dll's que você baixou e descompactou na primeira etapa e adicione referências às seguintes: Couchbase.NetClient.dll, Common.Logging.dll e Newtonsoft.Json.dll.

Depois de chegar até aqui, você pode começar a escrever o código. Observe que vou presumir que a instância do servidor Couchbase está em execução no localhost. Caso contrário, você terá de configurar seu cliente para apontar para a instalação remota.

Uma nova API QueryRequest

O suporte do SDK para o N1QL Developer Preview 3 (DP3) era mínimo: somente consultas ad-hoc de strings literais eram suportadas. Com a nova API REST, uma nova classe QueryClient foi criada e integrada à classe CouchbaseBucket, que fornece uma API de wrapper para a maioria dos novos recursos da API REST - digo "a maioria" porque alguns recursos ainda não foram concluídos.

Essa nova API inclui uma classe para a construção de consultas usando uma interface fluente. Ela é muito semelhante à classe/API ViewQuery que o cliente também suporta e que foi lançada como parte do SDK GA para consulta de visualizações. Ela tem a seguinte assinatura:

[imagem]

Você pode encadear os vários parâmetros da API REST construindo uma solicitação de consulta usando uma instrução N1QL. A instrução N1QL em si ainda é uma string literal, mas você pode fornecer opções que permitem controlar como o serviço de consulta lida com a consulta. Não abordarei cada um desses parâmetros nesta publicação; deixarei isso para outra publicação do blog.

Observe que o QueryRequest não tem nada a ver com a linguagem N1QL? Isso é intencional. Há outro projeto em andamento que lida com a criação da consulta N1QL: um provedor de consulta integrada à linguagem (LINQ) para N1QL, que ainda está em desenvolvimento.

O que esse objeto faz é facilitar a gravação de uma solicitação de consulta sem ter que criá-la manualmente usando o intellisense do IDE e o ponto "." operador. Por exemplo:

Criação de índices

No exemplo a seguir, mostrarei como usar o QueryRequest acima e o Couchbase .NET SDK 2.0 N1QL DP4 Preview para criar e remover índices em tempo real:

Aqui, primeiro consultamos o "catálogo" do sistema para determinar quais compartimentos têm índices. Um bucket com um índice será retornado nessa lista. Se o índice existir, nós o eliminaremos (para que possamos recriá-lo de forma conveniente). Por fim, estamos recriando o índice. Observe que você normalmente não faria isso na produção, mas estamos aqui para ilustrar a funcionalidade fornecida pelo N1QL e pelo SDK.

Uso de parâmetros nomeados e parâmetros posicionais

O N1QL DP4 apresenta um recurso para a criação de consultas parametrizadas. Existe a funcionalidade para parâmetros nomeados, que são como pares nome/valor, e também para parâmetros posicionais, em que a posição do parâmetro corresponde ao seu ordinal.
Aqui está um exemplo de uma consulta que usa parâmetros posicionais:

        static void PositionalParameters(IBucket bucket)
        {
            var queryRequest = new QueryRequest()
                .Statement("SELECT * FROM amostra de cerveja WHERE type=$1 LIMIT $2″)
                .AddPositionalParameter("beer")
                .AddPositionalParameter(10);

            var result = bucket.Query(queryRequest);
            foreach (var row in result.Rows)
            {
                Console.WriteLine(row);
            }
        }

Observe que, no momento, os parâmetros posicionais não são indexados a zero! Portanto, se você substituísse $1 e $2 por $0 e $1, receberia uma mensagem de erro.
Mais uma vez, os parâmetros nomeados são como pares nome/valor e, ao contrário dos parâmetros posicionais, a ordem não é importante. Aqui está a mesma consulta acima usando parâmetros nomeados:

        static void NamedParameters(IBucket bucket)
        {
            var queryRequest = new QueryRequest()
                .Statement("SELECT * FROM amostra de cerveja WHERE type=$type LIMIT $limit")
                .AddNamedParameter("limit", 10)
                .AddNamedParameter("type", "beer");

            var result = bucket.Query(queryRequest);
            foreach (var row in result.Rows)
            {
                Console.WriteLine(row);
            }
        }

Observe que essa é a mesma declaração anterior, mas eu reordenei os parâmetros quando criei o QueryRequest para mostrar que a ordem não é importante.

Declarações preparadas

Os comandos preparados são semelhantes aos planos de consulta em cache nos bancos de dados relacionais. O que eles fazem é permitir que você incorra apenas no custo de analisar a consulta uma vez e, em seguida, o comando preparado pode ser usado várias vezes. Embora isso esteja incluído no N1QL DP4, o suporte do SDK para esse recurso está incompleto (ele simplesmente não funciona ainda). Espera-se que isso funcione em uma versão posterior, quando o código de visualização tiver sido mesclado com o ramo principal do SDK.

Em conclusão

Então, isso é tudo sobre a prévia do Couchbase .NET SDK 2.0 N1QL DP4! Há muito, muito mais a ser analisado e publicarei mais blogs à medida que o desenvolvimento avançar e nos aproximarmos do N1QL GA!

Se você tiver algum feedback ou se deparar com problemas ou bugs, deixe um comentário ou publique um bug no Jira aqui. Além disso, o código que foi incluído neste blog pode ser encontrado no github aqui.