API de consulta JavaScript no Azure Cosmos DB

  • Artigo

APLICA-SE A: NoSQL

Além de emitir consultas usando a API para NoSQL no Azure Cosmos DB, o SDK do lado do servidor do Azure Cosmos DB fornece uma interface em JavaScript para a execução de consultas otimizadas em procedimentos e gatilhos armazenados no Cosmos DB. Você não precisa estar ciente da linguagem SQL para usar essa interface JavaScript. A API de consulta do JavaScript permite a você criar consultas de forma programática passando funções de predicado em uma sequência de chamadas de função, com uma sintaxe similar para bibliotecas JavaScript internas e populares da matriz do ECMAScript5, como Lodash. As consultas são analisadas no runtime do JavaScript e executadas com eficiência usando índices do Azure Cosmos DB.

Funções do JavaScript com suporte

Função Descrição
chain() ... .value([callback] [, options]) Inicia uma chamada encadeada que deve ser terminada com value().
filter(predicateFunction [, options] [, callback]) Filtra a entrada usando uma função de predicado que retorna true/false para filtrar documentos de entrada no conjunto resultante. Essa função se comporta semelhante a uma cláusula WHERE no SQL.
flatten([isShallow] [, options] [, callback]) Combina e nivela as matrizes de cada item de entrada em uma única matriz. Essa função se comporta semelhante a uma cláusula SelectMany no LINQ.
map(transformationFunction [, options] [, callback]) Aplica uma projeção dada uma função de transformação que mapeia cada item de entrada para um objeto ou valor JavaScript. Essa função se comporta semelhante a uma cláusula SELECT no SQL.
pluck([propertyName] [, options] [, callback]) Essa função é um atalho para um mapa que extrai o valor de uma única propriedade de cada item de entrada.
sortBy([predicate] [, options] [, callback]) Produz um novo conjunto de documentos classificando os documentos no fluxo de documentos de entrada em ordem ascendente usando o predicado fornecido. Essa função se comporta semelhante a uma cláusula ORDER BY no SQL.
sortByDescending([predicate] [, options] [, callback]) Produz um novo conjunto de documentos classificando os documentos no fluxo de documentos de entrada em ordem decrescente usando o predicado fornecido. Essa função se comporta semelhante a uma cláusula ORDER BY x DESC no SQL.
unwind(collectionSelector, [resultSelector], [options], [callback]) Executa uma autojunção com a matriz interna e adiciona os resultados de ambos os lados como tuplas à projeção de resultados. Por exemplo, o ingresso de um documento de pessoas com person.pets produzirá as tuplas [pessoas, animais de estimação]. Isso é semelhante a SelectMany no LINQ do .NET.

Quando incluídas em funções de predicado e/ou do seletor, os constructos do JavaScript a seguir são automaticamente otimizados para serem executados diretamente nos índices do Azure Cosmos DB:

  • Operadores simples: =+-*/%|^&==!====!==<><=>=||&&<<>>>>>~
  • Literais, incluindo o literal de objeto: {}
  • var, return

Os seguintes constructos do JavaScript não são otimizados pelos índices do Azure Cosmos DB:

  • Fluxo de controle: if for while
  • Chamadas de função

Para saber mais, confira a Documentação do JavaScript do lado do servidor do Azure Cosmos DB.

Folha de referências do SQL para JavaScript

A tabela a seguir apresenta várias consultas SQL e as consultas JavaScript correspondentes. Assim como acontece com consultas SQL, as propriedades (por exemplo, item.id) diferenciam maiúsculas de minúsculas.

Observação

__ (sublinhado duplo) é um alias para getContext().getCollection() ao usar a API de consulta do JavaScript.

SQL API de Consulta do JavaScript Descrição
SELECIONAR *
FROM docs		 __.map(function(doc) {
    return doc;
});		 Resulta em todos os documentos (paginados com token de continuação) no estado em que se encontram.
SELECT
   docs.id,
   docs.message AS msg,
   docs.actions
FROM docs		 __.map(function(doc) {
    return {
        id: doc.id,
        msg: doc.message,
        actions:doc.actions
    };
});		 Projeta a ID, a mensagem (com o alias msg) e a ação de todos os documentos.
SELECIONAR *
FROM docs
WHERE
   docs.id="X998_Y998"		 __.filter(function(doc) {
    return doc.id ==="X998_Y998";
});		 Consulta documentos com o predicado : id = "X998_Y998".
SELECIONAR *
FROM docs
WHERE
   ARRAY_CONTAINS(docs.Tags, 123)		 __.filter(function(x) {
    return x.Tags && x.Tags.indexOf(123) > -1;
});		 Consulta documentos com uma propriedade Tags e Tags é uma matriz que contém o valor 123.
SELECT
   docs.id,
   docs.message AS msg
FROM docs
WHERE
   docs.id="X998_Y998"		 __.chain()
    .filter(function(doc) {
        return doc.id ==="X998_Y998";
    })
    .map(function(doc) {
       return {
            id: doc.id,
            msg: doc.message
       };
    })
.value();		 Consulta documentos com um predicado, id = "X998_Y998" e projeta a ID e a mensagem (com alias para msg).
SELECT VALUE tag
FROM docs
JOIN tag IN docs.Tags
ORDER BY docs._ts		 __.chain()
    .filter(function(doc) {
        return doc.Tags && Array.isArray(doc.Tags);
    })
    .sortBy(function(doc) {
        return doc._ts;
    })
    .pluck("Tags")
    .flatten()
    .value()		 Filtra documentos que têm uma propriedade de matriz, Tags, e classifica os documentos resultantes pela propriedade do sistema do carimbo de data/hora _ts e projeta + mescla a matriz Tags.

Próximas etapas

Conheça mais conceitos e saiba como escrever e usar procedimentos armazenados, gatilhos e funções definidas pelo usuário no Azure Cosmos DB: