Trabalhando com matrizes JSON no N1QL

A linguagem de consulta N1QL tem um rico conjunto de recursos para trabalhar com matrizes JSON. Neste artigo, abordaremos as constantes de matriz, os recursos de pesquisa em matrizes, as formas de transformar matrizes e algumas funções úteis de matriz N1QL. O formato é interativo; abra uma instância do Couchbase e experimente os exemplos você mesmo.

Para começar, acesse o console de administração da sua instância do Couchbase e crie um bucket chamado "test".

Como alternativa, você pode criar o bucket na linha de comando, da seguinte forma:

curl -X POST -u Administrator:password -d name=test -d ramQuotaMB=100 -d authType=sasl -d saslPassword=donotuse -d proxyPort=11224 -d bucketType=couchbase http://localhost:8091/pools/default/buckets

Conecte-se à instância usando o shell CBQ da seguinte forma:

cbq -e http://localhost:8091 -u Administrator -p password

Em seguida, no CBQ, crie um índice primário em seu novo bucket:

cbq> create primary index on test;

Agora estamos prontos para começar.

Constantes de matriz do Couchbase

Em primeiro lugar, o N1QL permite que você crie valores de matriz diretamente como constantes de matriz, da seguinte forma:

cbq> select [1,2,3] as num_array, ["a", "b", "c"] as string_array, ["1", 2, [3, "4"], {"a": "b"}] as mixed_array;

As constantes podem até incluir valores extraídos do banco de dados:
cbq> insert into test (key, value) values ("ex1", {"v1" : 7, "v2" : "bird", "v3" : 99});

cbq> select [1, v1, 3] as num_array, ["a", v2, "c"] as string_array from test where v3 = 99;

Também há suporte para a seleção de elementos por índice baseado em zero:

cbq> select ["apple", "banana", "cherry", "date", "elderberry"][1] as val;

Matrizes de consulta do Couchbase e pesquisa em matrizes

A cláusula IN é usada para testar a associação.

cbq> select (9 IN [1, 2, 3, 4]) as not_found, (9 in [7, 8, 9]) as is_found;

A cláusula ANY é usada para verificar se pelo menos um elemento da matriz corresponde a alguma condição:

cbq> select (ANY v IN [1, 2, 3, 4, 5] SATISFIES v > 4 END) as is_found, (ANY v IN [1, 2, 3, 4, 5] SATISFIES v = 7 END) as not_found;

A cláusula EVERY é usada para verificar se todos os elementos de uma matriz correspondem a alguma condição:

cbq> select (EVERY v IN [1, 2, 3, 4, 5] SATISFIES v > 0 END) as is_found, (EVERY v in [-1, 0, 1, 2, 3] SATISFIES v > 0 END ) as not_found;

ANY AND EVERY é muito semelhante a EVERY, mas EVERY é verdadeiro para matrizes vazias, mas ANY AND EVERY é falso:

cbq> select (ANY AND EVERY v IN [] SATISFIES v > 0 END) as any_every_res, (EVERY v IN [] SATISFIES v > 0 END) as every_res;

Fatiamento

O operador [:] serve para fatiar, ou seja, pegar partes de matrizes.

cbq> select [1, 2, 3, 4, 5][1: 3] as res;

O primeiro valor na expressão de fatia é o índice a ser iniciado (baseado em zero); o segundo é o primeiro índice que deve ser excluído. Essa convenção deve ser familiar em outras linguagens de programação.

Tanto o início quanto o fim da fatia devem ser fornecidos. Os valores negativos são enumerados a partir do final da matriz:

cbq> select [1, 2, 3, 4, 5][1: -1] as res;

Transformando matrizes do Couchbase

A expressão ARRAY permite que você transforme uma matriz em outra.

cbq> select ARRAY v*2 FOR v IN [1, 2, 3, 4, 5] END as res;

A expressão ARRAY também oferece suporte à seleção:

cbq> select ARRAY v*2 FOR v IN [1, 2, 3, 4, 5] WHEN v > 2 END as res;

A expressão de destino pode incluir não apenas cada valor, mas também os índices:

cbq> SELECT ARRAY {v:pos} FOR pos:v IN [ "um", "dois", "três" ] END;

Para saber mais sobre operações de matriz no N1QL, consulte a documentação aqui.

Funções de matriz do Couchbase

O N1QL tem um amplo conjunto de funções para operar em matrizes JSON.

ARRAY_LENGTH retorna o comprimento de uma matriz.

cbq> select ARRAY_LENGTH([1, 2, 3, 4, 5]) as res;

ARRAY_APPEND adiciona elementos ao final de uma matriz.

cbq> select ARRAY_APPEND([1, 2, 3, 4, 5], 9, 10) as res;

ARRAY_CONCAT é semelhante, mas une duas matrizes.

cbq> select ARRAY_CONCAT([1, 2, 3, 4, 5], [7, 8]) as res;

ARRAY_SORT classifica os elementos de uma matriz.

cbq> select ARRAY_SORT([2, 1, 3, 5, 4]) as res;

E, por fim, ARRAY_DISTINCT remove as duplicatas de uma matriz.

cbq> select ARRAY_DISTINCT([1, 2, 3, 3, 4, 5, 4, 5]) as res;

Há muitas outras funções de matriz úteis no N1QL, muitas delas não podem ser abordadas aqui. Você pode encontrar a lista completa aqui.

Desempenho

"Mas e quanto ao desempenho das matrizes JSON?", você pergunta. Não se preocupe, isso será abordado em outro artigo, aqui.