API de consulta JavaScript no Azure Cosmos DBJavaScript query API in Azure Cosmos DB

Além de emitir consultas usando a API do SQL no Azure Cosmos DB, o SDK do servidor do Cosmos DB permite que você execute consultas otimizadas usando uma interface JavaScript.In addition to issuing queries using the SQL API in Azure Cosmos DB, the Cosmos DB server-side SDK allows you to perform optimized queries using a JavaScript interface. Você não precisa estar ciente da linguagem SQL para usar essa interface JavaScript.You don't have to be aware of the SQL language to use this JavaScript interface. A API de consulta do JavaScript permite que você crie consultas de forma programática passando funções de predicado em uma sequência de chamadas de função, com uma sintaxe conhecida para bibliotecas JavaScript internas e populares da matriz do ECMAScript5, como Lodash.The JavaScript query API allows you to programmatically build queries by passing predicate functions into sequence of function calls, with a syntax familiar to ECMAScript5's array built-ins and popular JavaScript libraries like Lodash. As consultas são analisadas no tempo de execução do JavaScript e executadas com eficiência usando índices do Azure Cosmos DB.Queries are parsed by the JavaScript runtime and efficiently executed using Azure Cosmos DB indices.

Funções do JavaScript com suporteSupported JavaScript functions

FunçãoFunction DescriçãoDescription
chain() ... .value([callback] [, options]) Inicia uma chamada encadeada que deve ser terminada com value().Starts a chained call that must be terminated with 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.Filters the input using a predicate function that returns true/false in order to filter in/out input documents into the resulting set. Essa função se comporta semelhante a uma cláusula WHERE no SQL.This function behaves similar to a WHERE clause in SQL.
flatten([isShallow] [, options] [, callback]) Combina e nivela as matrizes de cada item de entrada em uma única matriz.Combines and flattens arrays from each input item into a single array. Essa função se comporta semelhante a uma cláusula SelectMany no LINQ.This function behaves similar to SelectMany in 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.Applies a projection given a transformation function that maps each input item to a JavaScript object or value. Essa função se comporta semelhante a uma cláusula SELECT no SQL.This function behaves similar to a SELECT clause in 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.This function is a shortcut for a map that extracts the value of a single property from each input item.
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.Produces a new set of documents by sorting the documents in the input document stream in ascending order by using the given predicate. Essa função se comporta semelhante a uma cláusula ORDER BY no SQL.This function behaves similar to an ORDER BY clause in 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.Produces a new set of documents by sorting the documents in the input document stream in descending order using the given predicate. Essa função se comporta semelhante a uma cláusula ORDER BY x DESC no SQL.This function behaves similar to an ORDER BY x DESC clause in 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.Performs a self-join with inner array and adds results from both sides as tuples to the result projection. Por exemplo, o ingresso de um documento de pessoas com person.pets produzirá as tuplas [pessoas, animais de estimação].For instance, joining a person document with person.pets would produce [person, pet] tuples. Isso é semelhante a SelectMany no LINK do .NET.This is similar to SelectMany in .NET LINK.

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:When included inside predicate and/or selector functions, the following JavaScript constructs get automatically optimized to run directly on Azure Cosmos DB indices:

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

Os seguintes constructos do JavaScript não são otimizados pelos índices do Azure Cosmos DB:The following JavaScript constructs do not get optimized for Azure Cosmos DB indices:

  • Fluxo de controle (por exemplo, if, for, while)Control flow (for example, if, for, while)
  • Chamadas de funçãoFunction calls

Para obter mais informações, confira a Documentação do JavaScript do servidor do Cosmos DB.For more information, see the Cosmos DB Server Side JavaScript Documentation.

Folha de referências do SQL para JavaScriptSQL to JavaScript cheat sheet

A tabela a seguir apresenta várias consultas SQL e as consultas JavaScript correspondentes.The following table presents various SQL queries and the corresponding JavaScript queries. Assim como acontece com consultas SQL, as propriedades (por exemplo, item.id) diferenciam maiúsculas de minúsculas.As with SQL queries, properties (for example, item.id) are case-sensitive.

Observação

__ (sublinhado duplo) é um alias para getContext().getCollection() ao usar a API de consulta do JavaScript.__ (double-underscore) is an alias to getContext().getCollection() when using the JavaScript query API.

SQLSQL API de Consulta do JavaScriptJavaScript Query API DescriçãoDescription
SELECIONAR *SELECT *
FROM docsFROM docs
.map(function(doc) {.map(function(doc) {
    return doc;    return doc;
});});
Resulta em todos os documentos (paginados com token de continuação) no estado em que se encontram.Results in all documents (paginated with continuation token) as is.
SELECIONARSELECT
   docs.id,   docs.id,
   docs.message AS msg,   docs.message AS msg,
   docs.actions   docs.actions
FROM docsFROM docs
.map(function(doc) {.map(function(doc) {
    return {    return {
        id: doc.id,        id: doc.id,
        msg: doc.message,        msg: doc.message,
        actions:doc.actions        actions:doc.actions
    };    };
});});
Projeta a ID, a mensagem (com o alias msg) e a ação de todos os documentos.Projects the id, message (aliased to msg), and action from all documents.
SELECIONAR *SELECT *
FROM docsFROM docs
WHEREWHERE
   docs.id="X998_Y998"   docs.id="X998_Y998"
.filter(function(doc) {.filter(function(doc) {
    return doc.id ==="X998_Y998";    return doc.id ==="X998_Y998";
});});
Consulta documentos com o predicado : id = "X998_Y998".Queries for documents with the predicate: id = "X998_Y998".
SELECIONAR *SELECT *
FROM docsFROM docs
WHEREWHERE
   ARRAY_CONTAINS(docs.Tags, 123)   ARRAY_CONTAINS(docs.Tags, 123)
.filter(function(x) {.filter(function(x) {
    return x.Tags && x.Tags.indexOf(123) > -1;    return x.Tags && x.Tags.indexOf(123) > -1;
});});
Consulta documentos com uma propriedade Tags e Tags é uma matriz que contém o valor 123.Queries for documents that have a Tags property and Tags is an array containing the value 123.
SELECIONARSELECT
   docs.id,   docs.id,
   docs.message AS msg   docs.message AS msg
FROM docsFROM docs
WHEREWHERE
   docs.id="X998_Y998"   docs.id="X998_Y998"
.chain().chain()
    .filter(function(doc) {    .filter(function(doc) {
        return doc.id ==="X998_Y998";        return doc.id ==="X998_Y998";
    })    })
    .map(function(doc) {    .map(function(doc) {
       return {       return {
            id: doc.id,            id: doc.id,
            msg: doc.message            msg: doc.message
       };       };
    })    })
.value();.value();
Consulta documentos com um predicado, id = "X998_Y998" e projeta a ID e a mensagem (com alias para msg).Queries for documents with a predicate, id = "X998_Y998", and then projects the id and message (aliased to msg).
SELECT VALUE tagSELECT VALUE tag
FROM docsFROM docs
JOIN tag IN docs.TagsJOIN tag IN docs.Tags
ORDER BY docs._tsORDER BY docs._ts
.chain().chain()
    .filter(function(doc) {    .filter(function(doc) {
        return doc.Tags && Array.isArray(doc.Tags);        return doc.Tags && Array.isArray(doc.Tags);
    })    })
    .sortBy(function(doc) {    .sortBy(function(doc) {
        return doc._ts;        return doc._ts;
    })    })
    .pluck("Tags")    .pluck("Tags")
    .flatten()    .flatten()
    .value()    .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.Filters for documents that have an array property, Tags, and sorts the resulting documents by the _ts timestamp system property, and then projects + flattens the Tags array.

Próximas etapasNext steps

Conheça mais conceitos e saiba como escrever e usar procedimentos armazenados, gatilhos e funções definidas pelo usuário no Azure Cosmos DB:Learn more concepts and how-to write and use stored procedures, triggers, and user-defined functions in Azure Cosmos DB: