API de requête JavaScript dans Azure Cosmos DBJavaScript query API in Azure Cosmos DB

Outre l'émission de requêtes à l'aide de l'API SQL dans Azure Cosmos DB, le kit SDK côté serveur Cosmos DB fournit une interface JavaScript pour exécuter des requêtes optimisées dans les procédures stockées et déclencheurs Cosmos DB.In addition to issuing queries using the SQL API in Azure Cosmos DB, the Cosmos DB server-side SDK provides a JavaScript interface for performing optimized queries in Cosmos DB Stored Procedures and Triggers. Vous n’êtes pas obligé de connaître le langage SQL pour utiliser cette interface JavaScript.You don't have to be aware of the SQL language to use this JavaScript interface. L’API de requête JavaScript permet de créer des requêtes par programmation, en transmettant des fonctions de prédicat dans une séquence d’appels de fonction, avec une syntaxe usuelle des types prédéfinis de tableau ECMAScript5 et des bibliothèques JavaScript courantes, telles que 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. Les requêtes sont analysées par le runtime JavaScript et exécutées efficacement à l’aide d’index Azure Cosmos DB.Queries are parsed by the JavaScript runtime and efficiently executed using Azure Cosmos DB indices.

Fonctions JavaScript prises en chargeSupported JavaScript functions

FonctionFunction DescriptionDescription
chain() ... .value([callback] [, options]) Commence un appel chaîné qui doit se terminer par value().Starts a chained call that must be terminated with value().
filter(predicateFunction [, options] [, callback]) Filtre l’entrée à l’aide d’une fonction de prédicat qui renvoie true/false afin de filtrer les documents d’entrée dans le jeu résultant.Filters the input using a predicate function that returns true/false in order to filter in/out input documents into the resulting set. Cette fonction se comporte comme une clause WHERE dans SQL.This function behaves similar to a WHERE clause in SQL.
flatten([isShallow] [, options] [, callback]) Combine et aplatit les tableaux à partir de chaque élément d’entrée en un seul tableau.Combines and flattens arrays from each input item into a single array. Cette fonction se comporte comme SelectMany dans SQL.This function behaves similar to SelectMany in LINQ.
map(transformationFunction [, options] [, callback]) Applique une projection à partir d’une fonction de transformation qui mappe chaque élément d’entrée à une valeur ou un objet JavaScript.Applies a projection given a transformation function that maps each input item to a JavaScript object or value. Cette fonction se comporte comme une clause SELECT dans SQL.This function behaves similar to a SELECT clause in SQL.
pluck([propertyName] [, options] [, callback]) Cette fonction est un raccourci pour un mappage qui extrait la valeur d’une propriété unique de chaque élément d’entrée.This function is a shortcut for a map that extracts the value of a single property from each input item.
sortBy([predicate] [, options] [, callback]) Produit un nouvel ensemble de documents, en triant les documents dans le flux de documents d’entrée, dans l’ordre croissant avec le prédicat donné.Produces a new set of documents by sorting the documents in the input document stream in ascending order by using the given predicate. Cette fonction se comporte comme une clause ORDER BY dans SQL.This function behaves similar to an ORDER BY clause in SQL.
sortByDescending([predicate] [, options] [, callback]) Produit un nouvel ensemble de documents, en triant les documents dans le flux de documents d’entrée, dans l’ordre décroissant avec le prédicat donné.Produces a new set of documents by sorting the documents in the input document stream in descending order using the given predicate. Cette fonction se comporte comme une clause ORDER BY x DESC dans SQL.This function behaves similar to an ORDER BY x DESC clause in SQL.
unwind(collectionSelector, [resultSelector], [options], [callback]) Effectue une jointure réflexive avec tableau interne et ajoute les résultats des deux côtés, sous forme de tuples, à la projection de résultats.Performs a self-join with inner array and adds results from both sides as tuples to the result projection. Par exemple, joindre un document person avec person.pets produirait des tuples [person, pet].For instance, joining a person document with person.pets would produce [person, pet] tuples. Ce comportement est semblable à SelectMany dans .NET LINK.This is similar to SelectMany in .NET LINK.

Quand elles sont incluses dans les fonctions de prédicat et/ou de sélecteur, les constructions JavaScript suivantes sont automatiquement optimisées pour s’exécuter directement sur les index 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:

  • Opérateurs simples : = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~Simple operators: = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~
  • Littéraux, notamment le littéral d’objet : {}Literals, including the object literal: {}
  • var, returnvar, return

Les constructions JavaScript suivantes ne sont pas optimisées pour les index Azure Cosmos DB :The following JavaScript constructs do not get optimized for Azure Cosmos DB indices:

  • Flux de contrôle (par exemple, if, for, while)Control flow (for example, if, for, while)
  • Appels de fonctionFunction calls

Pour plus d’informations, consultez la documentation JavaScript Azure Cosmos DB côté serveur.For more information, see the Cosmos DB Server Side JavaScript Documentation.

Aide-mémoire SQL vers JavaScriptSQL to JavaScript cheat sheet

Le tableau suivant présente différentes requêtes SQL et les requêtes JavaScript correspondantes.The following table presents various SQL queries and the corresponding JavaScript queries. Comme pour les requêtes SQL, les propriétés (par exemple, item.id) respectent la casse.As with SQL queries, properties (for example, item.id) are case-sensitive.

Notes

__ (trait de soulignement double) est un alias pour getContext().getCollection() lors de l’utilisation de l’API de requête JavaScript.__ (double-underscore) is an alias to getContext().getCollection() when using the JavaScript query API.

SQLSQL API de requête JavaScriptJavaScript Query API DescriptionDescription
SELECT *SELECT *
FROM docsFROM docs
.map(function(doc) {.map(function(doc) {
    return doc;    return doc;
});});
Renvoie tous les documents (paginés avec jeton de continuation) tels quels.Results in all documents (paginated with continuation token) as is.
SELECTSELECT
   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
    };    };
});});
Projette l’ID, le message (alias msg) et l’action de tous les documents.Projects the id, message (aliased to msg), and action from all documents.
SELECT *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";
});});
Requêtes pour les documents avec le prédicat : id = "X998_Y998".Queries for documents with the predicate: id = "X998_Y998".
SELECT *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) &gt; -1;    return x.Tags && x.Tags.indexOf(123) > -1;
});});
Requêtes pour les documents comportant une propriété Tags, et Tags est un tableau contenant la valeur 123.Queries for documents that have a Tags property and Tags is an array containing the value 123.
SELECTSELECT
   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();
Interroge les documents avec un prédicat, id = "X998_Y998", puis projette l’ID et le message (alias 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()
Filtre les documents comportant une propriété de tableau, Tags, trie les documents résultants par la propriété système _ts timestamp, puis projette et aplatit le tableau 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.

Étapes suivantesNext steps

Découvrez plus de concepts, et comment écrire et utiliser procédures stockées, déclencheurs et fonctions définies par l’utilisateur dans Azure Cosmos DB :Learn more concepts and how-to write and use stored procedures, triggers, and user-defined functions in Azure Cosmos DB: