Apresentando a interface de consulta no Couchbase Mobile 2.0

A versão 2.0 do Couchbase Lite traz uma infinidade de Novos recursos e aprimoramentos. Discutimos um desses aprimoramentos, ou seja, o novo protocolo de replicação entre em um artigo anterior postagem no blog sobre Replicação 2.0. Nesta postagem do blog, apresentaremos a você outro recurso importante: a interface de consulta do Couchbase Lite. A nova interface de consulta é baseada em N1QLa linguagem de consulta declarativa do Couchbase que estende o SQL para JSON. Se você estiver familiarizado com SQL, vai se sentir em casa com a semântica da nova API.

Esta publicação apresenta a interface de consulta e aborda os conceitos básicos. Consulte a última seção desta postagem para obter detalhes sobre outras postagens de blog relacionadas a recursos de consulta mais avançados.

Você pode fazer o download das compilações de pré-lançamento do Couchbase Mobile 2.0 em nosso downloads página.

Histórico

Se você estava usando as versões 1.x do Couchbase Mobile, provavelmente está familiarizado Visualizações de mapas para criar índices e consultas. Na versão 2.0, você não precisa mais criar visualizações e funções de mapa! Em vez disso, uma interface simples permite a criação de índices e você pode usar uma interface do Query Builder para construir suas consultas. A nova interface de consulta é mais simples de usar e muito mais poderosa em comparação. Vamos descobrir alguns de seus recursos nesta postagem.

Projeto de amostra

Embora os exemplos discutidos aqui usem o Swift para iOS, observe que, salvo algumas pequenas diferenças, a mesma interface de consulta também é compatível com as plataformas Android e Windows. Portanto, com alguns pequenos ajustes, você poderá reutilizar os exemplos desta publicação ao trabalhar com outras plataformas.

Siga as instruções abaixo se você estiver interessado em um projeto Swift de amostra

• Clone o iOS Swift Playground do GitHub
  
  $ git clone https://github.com/couchbaselabs/couchbase-lite-ios-api-playground

  1	$ git clone https://github.com/couchbaselabs/couchbase-lite-ios-api-playground

• Siga as instruções de instalação no manual correspondente LEIAME para criar e executar o playground.

Modelo de dados de amostra

Usaremos o banco de dados Travel Sample localizado aqui

O conjunto de dados de amostra inclui vários tipos de documentos, conforme identificado pelo tipo no documento. Vamos nos concentrar em documentos de tipo "hotel" e "marco". O modelo de documento JSON é mostrado abaixo. Para simplificar, omitimos algumas das propriedades do modelo abaixo.

O básico

Abertura/criação de um banco de dados

Para todas as consultas abaixo, usaremos o Banco de dados API para abrir/criar o banco de dados CouchbaseLite.

Índices

Para acelerar as consultas de leitura, você pode criar índices nas propriedades que serão consultadas. A melhoria no desempenho seria significativa em grandes conjuntos de dados. Obviamente, esteja ciente de que haverá um aumento na necessidade de armazenamento para guardar os índices, e o desempenho das gravações também poderá ser afetado. Portanto, tenha cuidado ao criar muitos índices.

O exemplo a seguir cria um Índice de valor no tipo propriedade de um documento

O exemplo a seguir cria um Índice de valor em tipo e nome propriedades de um documento

Obtenção de documentos do banco de dados

Uma consulta no Couchbase Lite é construída usando a API do construtor de consultas.

A consulta abaixo obtém todos os documentos do banco de dados especificado. Para cada documento que corresponda à consulta, todas as propriedades associadas ao documento são obtidas.

Obtenção de documentos do banco de dados com paginação

Esta é a estrutura de uma consulta simples que busca limite número de documentos do banco de dados a partir do número especificado compensação. Para cada documento que corresponda à consulta, todas as propriedades associadas ao documento são obtidas.

Valores de retorno usando SelectResult

A SelecionarResultado representa um único valor de retorno da instrução de consulta. Os documentos no Couchbase Lite são compostos pelas propriedades do documento especificadas como um dicionário de pares chave-valor e metadados associados. Os metadados consistem no ID do documento e no ID da sequência associados ao documento. Quando você consulta um documento, os metadados do documento não são retornados por padrão. Você precisará consultar explicitamente os metadados.

• SelectResult.all()
  • Retorna todas as propriedades associadas a um documento
• SelectResult(Expressão)
  • Retorna as propriedades de um documento com base no Expressão. Discutiremos os vários tipos de expressões um pouco mais adiante.
• SelectResult.expression(Expression.Meta.id)
  • Retorna o ID do documento
• SelectResult.expression(Expression.Meta.sequence)
  • Retorna o ID da sequência (usado em replicações)

Você pode especificar uma lista separada por vírgulas de SelecionarResultado expressões no selecionar declaração de sua consulta.
Por exemplo, o seguinte comando select consulta o ID do documento, bem como o tipo e nome propriedades do documento

Expressão de consulta

Uma expressão de consulta é usada para criar uma declaração de consulta

O Couchbase Lite inclui suporte para o seguinte Expressão Tipos.

• Propriedade
• Agregado
• Cordas
• Coleta
• Regex
• FTS
• Operador de verificação de nulidade
• Expressões aritméticas
• Metadados
• Correspondência de padrões
• Comparação
• Coleção
• Função
• Parâmetro
• Quantificado
• Operador bit a bit

Processamento de respostas de consulta

O resultado da execução da consulta é uma matriz em que cada membro da matriz é um Dictionary/Map correspondente a um documento que satisfaz a consulta.

• Se você estiver consultando todas as propriedades do documento usando SelectResult.all()cada membro da matriz de resposta é um par de chave-valor, em que o nome do banco de dados é a chave e o dicionário correspondente ao documento é o valor da chave.

• Os resultados seriam mais ou menos assim (onde "travel-sample" é o nome do banco de dados)
  
  [ { "travel-sample": { "callsign": "MILE-AIR", "country": "United States", "iata": "Q5", "icao": "MLA", "id": 10, "name": "40-Mile Air", "type": "airline" } }, { "travel-sample": { "callsign": "TXW", "country": "United States", "iata": "TQ", "icao": "TXW", "id": 10123, "name": "Texas Wings", "type": "airline" } } ]

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

  [     {         "amostra de viagem": {             "indicativo": "MILE-AIR",             "país": "Estados Unidos",             "iata": "Q5",             "icao": "MLA",             "id": 10,             "name" (nome): "40 milhas aéreas",             "tipo": "companhia aérea"         }     },     {         "amostra de viagem": {             "indicativo": "TXW",             "país": "Estados Unidos",             "iata": "TQ",             "icao": "TXW",             "id": 10123,             "name" (nome): "Texas Wings" (Asas do Texas),             "tipo": "companhia aérea"         }     } ]

  
  O trecho de código abaixo é um exemplo (em Swift) de como você processaria os resultados acima para obter os detalhes do objeto de documento
  
  Rápido

  for row in try searchQuery.execute() { if let dict = row.toDictionary() as? [String:Any], let docObject = dict["travel-sample"] as? [String:Any] { // You can now process the document properties let name = docObject["name"] let type = docObject["type"] } }

  1 2 3 4 5 6 7 8

  para fila em tentar pesquisa.executar() {         se deixar ditado = fila.toDictionary() como? [Cordas:Qualquer],             deixar docObjeto = ditado["amostra de viagem"] como? [Cordas:Qualquer] {             // Agora você pode processar as propriedades do documento             deixar nome = docObjeto["name" (nome)]             deixar tipo = docObjeto["tipo"]         }     }

  
   

• Se você estiver consultando o Id do documento usando SelectResult.expression(Expression.Meta.id)cada membro da matriz de resposta é um par de chave-valor, com "id" como a chave e o Id do documento como o valor.
  Por exemplo, considere a consulta

• Os resultados seriam mais ou menos assim -
  
  [ { "id": "airline_112" }, { "id": "airline_189" }, { "id": "airline_1209" } ]

  1 2 3 4 5 6 7 8 9 10 11

  [         {             "id": "airline_112"         },         {             "id": "airline_189"         },         {             "id": "airline_1209"         }     ]

  
  O trecho de código abaixo é um exemplo (em Swift) de como você processaria os resultados acima para obter os detalhes do objeto do documento usando o ID do documento
  
  Rápido

  for row in try searchQuery.execute() { if let dict = row.toDictionary() as? [String:Any], let docId = dict["id"] as? String { // You can now fetch the details of the document using the Id let doc = try db.getDocument(docId) } }

  1 2 3 4 5 6 7

  para fila em tentar pesquisa.executar() {         se deixar ditado = fila.toDictionary() como? [Cordas:Qualquer],             deixar docId  = ditado["id"] como? Cordas {             // Agora você pode obter os detalhes do documento usando o Id             deixar doc = tentar db.getDocument(docId)         }         }

• Se você estiver consultando propriedades específicas do documento usando, por exemplo, SelectResult.expression(Expression.property("type")cada membro da matriz de resposta é um par de chave-valor, com o nome da propriedade/propriedades como chave(s) e os valores de propriedade correspondentes como valor.

• Os resultados seriam mais ou menos assim -
  
  [ { "type": "airline" }, { "type": "airline" }, { "type": "hotel" } ]

  1 2 3 4 5 6 7 8 9 10 11

  [         {             "tipo": "companhia aérea"         },         {             "tipo": "companhia aérea"         },         {             "tipo": "hotel"         }     ]

  
  O trecho de código abaixo é um exemplo (em Swift) de como você processaria os resultados acima para obter os valores de propriedade que você consultou
  
  Rápido

  for row in try searchQuery.execute() { if let docObject = row.toDictionary() as? [String:Any] { // You can now fetch the details of the document using the property name as key let type = docObject["type"] } }

  1 2 3 4 5 6

  para fila em tentar pesquisa.executar() {    se deixar docObjeto = fila.toDictionary() como? [Cordas:Qualquer]  {       // Agora você pode buscar os detalhes do documento usando o nome da propriedade como chave          deixar tipo = docObjeto["tipo"]         }         }

  
  Você pode consultar os metadados e as propriedades do documento ao mesmo tempo usando uma lista separada por vírgulas de SelecionarResultado cada membro da matriz de resposta é um par de chave-valor, conforme discutido anteriormente. Por exemplo, considere a consulta
  
  Rápido

  let searchQuery = QueryBuilder .select(SelectResult.expression(Meta.id), SelectResult.expression(Expression.property("type"))) .from(DataSource.database(db)) .limit(Expression.int(limit))

  1 2 3 4 5

  deixar pesquisa = Criador de consultas             .selecionar(SelecionarResultado.expressão(Meta.id),                     SelecionarResultado.expressão(Expressão.propriedade("tipo")))             .de(Fonte de dados.banco de dados(db))             .limite(Expressão.int(limite))

  
  Os resultados seriam mais ou menos assim -
  
  [ { "id":"airline_1001", "type": "airline" }, { "id":"airline_900", "type": "airline" }, { "id":"hotel_1001", "type": "hotel" } ]

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  [         {             "id":"airline_1001",             "tipo": "companhia aérea"           },         {             "id":"airline_900",             "tipo": "companhia aérea"         },         {             "id":"hotel_1001",             "tipo": "hotel"         }     ]

  
  O trecho de código abaixo é um exemplo (em Swift) de como você processaria os resultados acima para obter os valores de propriedade que você consultou
  
  Rápido

  for row in try searchQuery.execute() { if let docObject = row.toDictionary() as? [String:Any] { // You can now fetch the details of the document using the property name as key let type = docObject["type"] let docId = docObject["id"] } }

  1 2 3 4 5 6 7

  para fila em tentar pesquisa.executar() {     se deixar docObjeto = fila.toDictionary() como? [Cordas:Qualquer]  {     // Agora você pode buscar os detalhes do documento usando o nome da propriedade como chave         deixar tipo = docObjeto["tipo"]         deixar docId = docObjeto["id"]      }     }

  
   

Apresentando a cláusula Where

Semelhante ao SQL, você pode usar o onde para filtrar os documentos a serem retornados como parte da consulta. A cláusula selecionar recebe uma instrução Expressão. Você pode encadear qualquer número de Expressões para implementar recursos sofisticados de filtragem.

Filtragem de documentos com base em uma propriedade específica

No exemplo abaixo, usamos Expressão de propriedade em conjunto com o tipo Expressões de comparação para filtrar documentos com base em uma propriedade específica do documento. O exemplo abaixo mostra o tipo igual a expressão de comparação.

Observação: Ao fazer referência a uma propriedade em um Expressão de propriedadePodemos usar caminhos de chave (em notação pontilhada) para especificar o caminho para uma propriedade aninhada.

A lista de operadores de comparação compatíveis inclui
* lessThan
* notLessThan
* lessThanOrEqualTo
* notLessThanOrEqualTo
* greaterThan
* notGreaterThan
* greaterThanOrEqualTo
* notGreaterThanOrEqualTo
* equalTo
* notEqualTo

Filtragem de documentos usando expressões lógicas

Podemos usar Expressão lógica para encadear vários expressões de comparação. No exemplo abaixo, buscamos documentos de tipo hotel cujo país é igual a "Estados Unidos" ou "França" e cujo vaga propriedade é verdadeiro. Em outras palavras, estamos buscando todos os hotéis nos Estados Unidos ou na França que têm uma vaga.

Correspondência de padrões

O como e regex podem ser usadas para correspondência de strings. Elas realizam correspondências **sensíveis a maiúsculas e minúsculas**. Portanto, se você quiser tornar a correspondência de strings insensível a maiúsculas e minúsculas, terá de usar Function.lower ou Function.upper para transformar a cadeia de caracteres correspondente em equivalentes em letras minúsculas ou maiúsculas.

Correspondência exata

No exemplo abaixo, estamos procurando documentos de tipo "marco" onde o nome corresponde exatamente à string "Museu dos engenheiros reais". Observe que, como como faz uma correspondência que diferencia maiúsculas de minúsculas, usamos Function.lower para transformar a string correspondente em um equivalente em letras minúsculas. Portanto, a consulta a seguir retornará "marco" tipo documentos com nome correspondência "Museu dos Engenheiros Reais", "Museu dos Engenheiros Reais", "MUSEU DOS ENGENHEIROS REAIS" e assim por diante.

Partida de coringa

Podemos usar % dentro de um como para fazer uma correspondência curinga com zero ou mais caracteres. O uso de curingas permite que você tenha alguma imprecisão em sua string de pesquisa.

No exemplo abaixo, estamos procurando documentos de tipo "marco" onde o nome corresponde a qualquer string que comece com "eng" seguido de zero ou mais caracteres, a letra "e", seguida de zero ou mais caracteres. Mais uma vez, estamos usando Function.lower para tornar o caso de pesquisa insensível.

A consulta a seguir retornará "marco" tipo documentos com nome correspondência "Engenheiros", "motor", "english egg" (ovo inglês) , "Inglaterra Eagle" e assim por diante. Observe que as correspondências podem abranger limites de palavras.

Correspondência de caracteres curinga

Podemos usar "_" dentro de um como para fazer uma correspondência curinga com um único caractere.

No exemplo abaixo, estamos procurando documentos de tipo "marco" onde o nome corresponde a qualquer cadeia de caracteres que comece com "eng", seguida de exatamente 4 caracteres curinga e terminando na letra "r".

Observe que, diferentemente dos exemplos anteriores, não estamos usando Function.lower para transformar a string de pesquisa em letras minúsculas. Assim, a pesquisa será sensível a maiúsculas e minúsculas.
A consulta a seguir retornará "marco" tipo documentos com nome correspondência "Engenheiro", "Engenheiro1" e assim por diante.

Correspondência Regex

O regex pode ser usada para correspondências que diferenciam maiúsculas de minúsculas. Semelhante ao curinga como expressões, regex A correspondência de padrões baseada em expressões permite que você tenha alguma imprecisão em sua string de pesquisa.

No exemplo abaixo, estamos procurando documentos de tipo "marco" onde o nome corresponde a qualquer cadeia de caracteres (em limites de palavras) que comece com "eng" seguido de exatamente 4 caracteres curinga e que termine com a letra "r". Mais uma vez, estamos usando Function.lower para tornar o caso de pesquisa insensível.

A consulta a seguir retornará "marco" tipo documentos com nome correspondência "Motor", "motor" e assim por diante. Observe que o \b especifica que a correspondência deve ocorrer nos limites das palavras.

Documentos que têm propriedade nula ou ausente

Um dos recursos da linguagem de consulta que a diferencia do SQL é a capacidade de consultar documentos que tenham propriedades nulas ou ausentes.

O isNullOrMissing() é usada em conjunto com a expressão Expressão de propriedade para testar se a propriedade especificada tem um valor nulo ou ausente. O isNullOrMissing() faz o inverso.

No exemplo abaixo, estamos procurando todos os documentos nos quais o e-mail que é nula ou está faltando.

Pedido de documentos

É possível classificar os resultados de uma consulta com base em um determinado resultado de expressão.

O exemplo abaixo retorna documentos de tipo igual a "hotel" classificadas em ordem crescente pelo valor da variável título propriedade.

Manipulação de cordas

Os recursos de manipulação de strings são essenciais para qualquer processamento de dados. Nos exemplos anteriores, vimos como a função Function.lower pode ser usado para transformar uma cadeia de caracteres em letras minúsculas equivalentes para fazer comparações de cadeias de caracteres sem distinção entre maiúsculas e minúsculas.

O Couchbase Lite oferece suporte às seguintes funções de processamento de strings.

O exemplo abaixo retorna documentos de onde o e-mail contém a substring "natgeo.org". O nome o valor da propriedade é convertido em maiúsculas na resposta.

Coleta

As funções de agrupamento aprimoram os recursos de comparação e classificação de strings, oferecendo suporte a strings unicode, manipulação de strings com reconhecimento local e recursos específicos do idioma, como diacríticos. Você pode aprender sobre collation neste escrever por Jens Alfke.

O exemplo abaixo define as regras de agrupamento que ignoram maiúsculas e minúsculas e acentos. Esse collator é aplicado à função de comparação de strings no nome propriedade. Os resultados incluirão documentos em que nome é igual a cadeias de caracteres como "Hotel Novotel Paris La Defense" , "Hotel Novotel Paris La Défense" e assim por diante.

Há algumas limitações no suporte ao Collation - no momento da redação deste post, ele não pode ser usado com consultas de correspondência de padrões, como como e regex .

Parametrização

Um dos recursos mais avançados da interface de consulta é a capacidade de definir parâmetros em uma consulta. Isso lhe dá a flexibilidade de atualizar os valores dos parâmetros de uma consulta a qualquer momento, sem precisar recriar ou reiniciar a consulta. A alteração dos parâmetros da consulta reiniciará automaticamente a consulta e os novos parâmetros entrarão em vigor.

Com relação ao modelo de dados acima, vamos supor que você queira buscar documentos em que o número gostos do público está dentro de um determinado intervalo. No exemplo abaixo, estamos procurando por "hotel" tipo documentos em que o número de gostos do público está entre 5 e 10.

Observe que, no exemplo acima, você deve ter notado o uso de ArrayFunction. O Couchbase Lite 2.0 nos fornece suporte extensivo à manipulação de array. Isso será discutido futuramente neste postagem no blog sobre coleções.

O que vem a seguir

Esta postagem do blog lhe deu um vislumbre da nova e poderosa interface de consulta suportada no Couchbase Lite 2.0. Você pode fazer o download das compilações de pré-lançamento do Couchbase Mobile 2.0 em nosso downloads página.

Aqui estão outras postagens relacionadas ao Couchbase Mobile Query que podem ser de interesse
- Isso postagem no blog discute os recursos de pesquisa de texto completo.
- Isso postagem no blog discute como consultar coleções de matrizes
- Isso postagem no blog discute como fazer consultas JOIN

Se tiver dúvidas ou comentários, deixe um comentário abaixo ou entre em contato comigo pelo Twitter @rajagp ou envie-me um e-mail priya.rajagopal@couchbase.com. O Fóruns do Couchbase são outro bom lugar para entrar em contato com perguntas.