Introdução ao Couchbase + Java [Passo a passo para desenvolvedores]

Se você é um desenvolvedor que está novo no Couchbase, este artigo o ajudará a começar.

Esta série semanal de orientações ajuda você a entender os fundamentos da conexão com o Couchbase, mostra como recuperar e modificar dados no Couchbase Server, como usar o a linguagem de consulta SQL++ (anteriormente conhecido como N1QL) e muito mais. Nesta semana, o código de exemplo apresentará Java e usaremos o Couchbase Java SDK.

Couchbase é um distribuído, Banco de dados de documentos JSON. Ele expõe um armazenamento de valores-chave com escalabilidade horizontal e cache gerenciado para operações de dados em menos de um milésimo de segundo, indexadores criados especificamente para consultas eficientes e um mecanismo de consulta avançado para executar consultas do tipo SQL.

Neste passo a passo para desenvolvedores, veremos os recursos básicos do Couchbase, tanto por meio de uma interface JSON não relacional quanto por meio de uma interface SQL relacional. O Couchbase vem com um banco de dados de amostra, amostra de viageme usaremos esse conjunto de dados de amostra para aprender os fundamentos do Couchbase usando o Java SDK.

Entendendo o conjunto de dados de amostra de viagens

Para entender melhor o que a amostra de viagem como é o conjunto de dados, fique à vontade para leia sobre isso na documentação do Java SDK: Modelo de dados de aplicativos de viagem.

Abaixo está um diagrama de entidade-relacionamento do amostra de viagem juntamente com um modelo de dados que o acompanha:

Como usar a função Key-Value Get para recuperar dados

O Key-value (também conhecido como Couchbase Data Service) oferece a maneira mais simples de recuperar ou alterar dados em que você conhece a chave. Um armazenamento de valor-chave é um tipo de Banco de dados NoSQL que usa um método simples para armazenar dados como uma coleção de pares de valores-chave em que uma chave serve como identificador exclusivo.

Servidor Couchbase é um armazenamento de valor-chave que é independente do que está armazenado. O exemplo abaixo mostra como usar o armazenamento de valor-chave obter para recuperar dados de um backend.

Antes de prosseguir, verifique se você conhece os conceitos básicos de autorização e conexão a um cluster do Couchbase. Leia a seção "Comece a usar o Java SDK" da documentação do Couchbase se você precisar se atualizar.

Abaixo estão as três importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar. Como você está usando Java, primeiro certifique-se de declarar uma classe e um método principal. Em seguida, crie uma variável para seu cluster.

No exemplo abaixo, agrupamento é o nome da variável do tipo var. Usando uma string de conexão, faça com que seu programa se conecte com os dados no backend. Uma string de conexão do Couchbase é uma lista delimitada por vírgulas de endereços IP e/ou nomes de host, opcionalmente seguida por uma lista de parâmetros. Abaixo, couchbase://127.0.0.1 é uma string de conexão simples com um nó inicial seguido de um nome de usuário e senha. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Uma conexão com um cluster do Couchbase Server é representada por um objeto de cluster. Um cluster fornece acesso a buckets, escopos e coleçõesalém de vários serviços e interfaces de gerenciamento do Couchbase.

Depois de fornecer a string de conexão, o nome de usuário e a senha acima, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket e a uma coleção do Couchbase:

O Java obter permite que você recupere uma determinada parte dos dados. Dada a chave de um documento, você pode usar o método collection.get() para recuperar um documento de uma coleção.

Neste exemplo, você está recuperando o conteúdo da coleção chamada "airline_10" no banco de dados. Em seguida, para ver o resultado, há um impressão que permite que você termine de recuperar os dados.

Por fim, para o caso de o usuário tentar recuperar uma informação que não existe ou não está dentro dos limites do documento, há uma função captura para garantir que não haja erros no código.

Usando o método de consulta para recuperar dados

Uma consulta é sempre realizada no nível do cluster, especificamente usando o consulta method. Esse método recebe a declaração como um argumento obrigatório e permite que ele forneça opções adicionais, se necessário.

Quando um resultado retornar, você poderá iterar as linhas retornadas e/ou acessar o QueryMetaData associado à consulta. Se algo der errado durante a execução da consulta, um derivado do CouchbaseException que também fornece contexto adicional sobre a operação.

Abaixo estão as cinco importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar, seguindo etapas semelhantes às anteriores. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Como antes, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket do Couchbase:

Este é um exemplo de execução de uma consulta e tratamento dos resultados. O resultado que é impresso é "Hotel: " seguido do nome, cidade, estado e outras informações específicas do hotel. Somente até cinco linhas serão impressas, pois esse é o número limite representado no código. Para testar diferentes consultas, tente alterar o nome da cidade na linha seis para qualquer outra cidade.

Como antes, o captura garante que não haja erros em seu código. Por exemplo, se você escolher uma cidade que seu banco de dados não possui, esta DocumentNotFoundException A exceção imprimirá "Documento não encontrado!".

Como consultar com parâmetros nomeados

Conforme mencionado anteriormente, os métodos de consulta permitem que você pesquise informações específicas em um banco de dados com base em determinados critérios. Os métodos de consulta podem ter parâmetros nomeados ou posicionais.

Nesta seção, veremos o que são parâmetros nomeados e como eles são úteis ao chamar métodos com um grande número de parâmetros. Os parâmetros nomeados indicam claramente o nome do parâmetro ao chamar um método. Eles permitem que os usuários invoquem o método com um subconjunto aleatório deles, usando valores padrão para o restante dos parâmetros.

Abaixo estão as sete importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar, seguindo etapas semelhantes às anteriores. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Como antes, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket do Couchbase:

O código prossegue para acessar o amostra de viagem e, especificamente, os compartimentos de nome, cidade e estado. Os queryOptions() permite a personalização de várias opções de consulta do SQL++.

No código abaixo, o resultado traz de volta dados de tipos: hotel e cidade: Malibu. Como o limite é cinco, somente até cinco linhas são impressas. O resultado impresso é "Hotel: " seguido de informações que incluem o nome e a cidade.

O resultado é obtido do amostra de viagem banco de dados, especificamente das linhas. As .stream é usado para computar elementos de acordo com o método primário sem alterar o valor original do objeto JSON.

Como antes, o captura A exceção garante que não haja erros em seu código. Por exemplo, se você escolher uma cidade ou um tipo de local que nosso banco de dados não tenha, esta CouchbaseException A exceção imprimirá "Exceção: " juntamente com a representação em string do objeto que está causando o erro.

Como fazer consultas com parâmetros posicionais

Conforme mencionado anteriormente, os métodos de consulta podem ter parâmetros nomeados ou posicionais. Abordamos os parâmetros nomeados acima.

Nesta seção, veremos os parâmetros posicionais e como eles são úteis ao chamar métodos com um grande número de parâmetros. Os parâmetros posicionais permitem que a ordem dos parâmetros do método seja substituída por espaços reservados.

Por exemplo, o primeiro espaço reservado é substituído pelo primeiro parâmetro de método, o segundo espaço reservado é substituído pelo segundo parâmetro de método e assim por diante.

Abaixo estão as sete importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar, seguindo etapas semelhantes às anteriores. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Como antes, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket do Couchbase:

A consulta abaixo busca o nome, a cidade e o estado no arquivo amostra de viagem levando em conta especificamente o tipo de lugar e a cidade. Posteriormente, eles são revelados como hotéis em Malibu.

Assim como no exemplo dos parâmetros nomeados acima, o .stream é usado para computar elementos de acordo com o método primário sem alterar o valor original do objeto JSON.

Como usar operações de pesquisa de subdocumentos

Subdocumentos são partes do documento JSON que você pode atualizar e recuperar de forma atômica e eficiente.

Enquanto as recuperações de documentos completos recuperam o documento inteiro e as atualizações de documentos completos exigem o envio do documento inteiro, as recuperações de subdocumentos recuperam apenas partes relevantes de um documento e as atualizações de subdocumentos exigem apenas o envio das partes atualizadas de um documento. Você deve usar as operações de subdocumento sempre que estiver modificando apenas partes de um documento e as operações de documento completo somente quando o conteúdo de um documento for alterado significativamente.

As operações de subdocumento descritas neste artigo são para somente solicitações de valor-chaveElas não estão relacionadas a consultas SQL++ de subdocumentos. Para usar operações de subdocumento, você precisa especificar um caminho que indique o local do subdocumento.

O lookupIn consulta o documento em busca de determinado(s) caminho(s) e retorna esse(s) caminho(s). Você tem a opção de realmente recuperar o caminho do documento usando a função subdoc obter ou simplesmente consultando a existência do caminho usando a operação de subdocumento subdoc existe operação de subdocumento. Essa última economiza ainda mais largura de banda, pois não recupera o conteúdo do caminho se ele não for necessário.

Abaixo estão as cinco importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar, seguindo etapas semelhantes às anteriores. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Como antes, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket do Couchbase:

No código abaixo, o lookupInconsulta o aeroporto_1254 para um determinado caminho, o geo.alt caminho. Esse código nos permite recuperar o caminho do documento usando o subdoc get operação de subdocumento: (get("geo.alt")).

Como antes, o captura garante que não haja erros em seu código. Por exemplo, se você escolher uma cidade que não existe em nosso banco de dados, esta DocumentNotFoundException A exceção imprimirá "Documento não encontrado!".

Como usar operações de mutação de subdocumentos

As operações de mutação de subdocumento modificam um ou mais caminhos no documento.

A mais simples dessas operações é subdoc upsert. Assim como o upsert de nível fulldoc, o subdoc upsert modifica o valor de um caminho existente ou o cria se ele não existir. Da mesma forma, a operação inserção de subdoc só adiciona o novo valor ao caminho se ele não existir.

Abaixo estão as oito importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar, seguindo etapas semelhantes às anteriores. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Como antes, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket do Couchbase:

No código abaixo, o mutateIn é usada para modificar a operação "airline_10" usando um upsert de nível fulldoc que criará o valor de um caminho existente com parâmetros ("país", "Canadá").

Como antes, o captura A exceção garante que não haja erros em seu código. Por exemplo, se você escolher um documento para o qual seu computador local não tem o caminho, esta PathNotFoundException A exceção imprimirá "Caminho do subdoc não encontrado!".

Como usar a função Upsert

A função Upsert é usado para inserir um novo registro ou atualizar um registro existente. Se o documento não existir, ele será criado. Upsert é uma combinação de inserir e atualização.

Os usuários que executam o upsert deve ter os privilégios Query Update e Query Insert no espaço-chave de destino. Se o comando tiver cláusulas de retorno, o privilégio Query Select também será necessário nos espaços-chave mencionados nas respectivas cláusulas. Para obter mais detalhes sobre as funções de usuário, consulte a documentação de Autorização sobre controle de acesso baseado em função (RBAC) no Couchbase.

Aqui está um diagrama da sintaxe básica para todas as operações de upsert:

Abaixo estão as nove importações de que você precisa:

Em seguida, conecte-se ao cluster que armazena os dados que você deseja recuperar, seguindo etapas semelhantes às anteriores. Certifique-se de substituir todas essas informações por informações relativas ao seu programa.

Como antes, você está conectado a um cluster do Couchbase e agora pode se conectar a um bucket do Couchbase:

O .put permite que o usuário insira um mapeamento em um mapa. Isso significa que você pode inserir uma chave específica (e o valor para o qual ela está mapeando) em um mapa específico. Se uma chave existente for passada, o valor anterior será substituído pelo novo valor.

Como antes, o captura A exceção garante que não haja erros em seu código. Por exemplo, se você escolher um documento para o qual seu computador local não tem o caminho, esta PathNotFoundException A exceção imprimirá "Documento não encontrado!".

Conclusão

Espero que este passo a passo introdutório tenha ajudado você a entender - e executar - algumas das funções mais comuns ao trabalhar com o Couchbase e o Java SDK. Para se aprofundar nas etapas intermediárias e avançadas, Confira a documentação do Java SDK aqui.

Se você precisar de ajuda ou de inspiração, Confira os fóruns do Couchbase e se conectar com desenvolvedores que pensam da mesma forma na comunidade.

Como próxima etapa, eu o encorajo a ler o guia on-line gratuito Curso de Certificação de Desenvolvedor Java Associado do Couchbase oferecido por Academia Couchbase.