De N1QL para JavaScript e vice-versa - Parte 2: Uso básico

O blog anterior apresentou a você novos recursos em funções definidas pelo usuário em JavaScript.

Agora vamos explorá-los em mais detalhes.

Começamos com um mecanismo básico para executar instruções N1QL dentro do código JavaScript.

N1QL em JavaScript

Há duas maneiras de executar instruções N1QL dentro de uma função JavaScript: chamando diretamente uma função apropriadamente chamada N1QL() ou permitindo que o compilador JavaScript detecte instruções N1QL incorporadas e produza chamadas N1QL() correspondentes.

Cada método é examinado a seguir.

Exemplo de pré-requisitos

As seções a seguir contêm vários exemplos.

Eles são totalmente funcionais, mas para executá-los você precisará:

• • um cluster do Couchbase, versão 7.1 ou mais recente
  • um balde chamado b1
  • um índice primário em b1
  • para criar cada função em uma biblioteca chamada udfbloge
  • para criar o UDF N1QL correspondente

Você pode usar a guia UDF no console da Web para criar a função e a UDF.

Função N1QL()

O N1QL() recebe uma declaração na forma de uma cadeia de caracteres e um segundo parâmetro opcional que contém valores de espaço reservado.

Tudo o que é necessário para executar uma instrução N1QL que não recebe parâmetros e não retorna valores é o seguinte: 

e o UDF correspondente:

(Esqueça por um segundo que a função em si não retorna nenhum valor. Além disso, peço desculpas pelos trechos de código mostrados como imagens, pois o WordPress não gostou de renderizá-los como texto).

Quando o N1QL() é chamada, a declaração passada no primeiro parâmetro é analisada, planejada e executada.

Se a instrução não retornar nenhum valor, no momento em que a função N1QL retornar, a instrução terá concluído a execução: nesse caso específico, supondo que o bucket b1 existe e uma chave k1 ainda não existir, um novo documento será inserido.

Se você estiver familiarizado com ESQL/C ou PL/SQL EXECUTAR IMEDIATAMENTE declaração, o N1QL() é o equivalente em UDF do JavaScript. 

Quando os valores são retornados, o valor de retorno de N1QL() é um iterador JavaScript, que pode ser usado para coletar valores um de cada vez, como veremos mais adiante. 

N1QL dinâmico

Obviamente, o outro uso do N1QL() é criar uma declaração dinamicamente concatenando cadeias de caracteres, por exemplo:

Embora isso seja perfeitamente legal, provavelmente é melhor não empregar essa técnica devido ao risco de injeção de N1QL (ou, de modo mais geral, de SQL) que ela acarreta.

Em vez disso, use marcadores de posição.

Transpilador de JavaScript

A segunda maneira de executar o N1QL é incorporar a instrução N1QL no corpo da função e permitir que o transpilador (um componente do compilador JavaScript) a detecte e crie as chamadas N1QL corretas nos bastidores:

Isso é muito conveniente para executar declarações estáticas imediatamente, e a função de repente se torna muito mais legível.

Espaços reservados para instruções N1QL e valores de espaço reservado

A melhor maneira de evitar os riscos associados à geração dinâmica de N1QL é ter instruções estáticas usando placeholders nomeados ou posicionais e passando valores de placeholder no momento da execução.

Função N1QL()

Ao usar o N1QL() isso pode ser feito passando os valores no segundo argumento opcional, como a seguir.

Parâmetros posicionais

Esse caso é coberto pela passagem de uma matriz de valores:

Parâmetros nomeados

Nesse caso, basta passar um objeto cujo nome de campo corresponda aos nomes dos parâmetros:

Não é possível misturar parâmetros posicionais e nomeados, o N1QL() aceita apenas uma matriz ou um objeto.

Observe que os valores passados para N1QL() não precisam ser literais, você pode construir matrizes e objetos a partir de variáveis ou pode passar uma matriz ou variável de objeto:

ou

Transpilador

Com o transpilador, somente parâmetros nomeados são possíveis; no entanto, usá-los é tão simples quanto usar variáveis já declaradas:

É claro que é possível usar parâmetros de função diretamente:

E o UDF N1QL correspondente:

Conclusão

Abordamos exemplos básicos de como usar o N1QL dentro de funções javascript, ambos usando o N1QL() e a incorporação da instrução N1QL diretamente no JavaScript, além de mostrar como usar parâmetros nomeados e posicionais.

A próxima postagem do blog abordará o iterador e as instruções de manipulação de dados.