API de requête JavaScript dans Azure Cosmos DB

  • Article

S’APPLIQUE À : NoSQL

Outre l’émission de requêtes à l’aide de l’API pour NoSQL dans Azure Cosmos DB, le kit SDK côté serveur Azure Cosmos DB fournit une interface JavaScript pour exécuter des requêtes optimisées dans les procédures stockées et déclencheurs Azure Cosmos DB. Vous n’êtes pas obligé de connaître le langage SQL pour utiliser cette interface JavaScript. 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. Les requêtes sont analysées par le runtime JavaScript et exécutées efficacement à l’aide d’index Azure Cosmos DB.

Fonctions JavaScript prises en charge

Fonction Description
chain() ... .value([callback] [, options]) Commence un appel chaîné qui doit se terminer par 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. Cette fonction se comporte comme une clause WHERE dans SQL.
flatten([isShallow] [, options] [, callback]) Combine et aplatit les tableaux à partir de chaque élément d’entrée en un seul tableau. Cette fonction se comporte comme SelectMany dans SQL.
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. Cette fonction se comporte comme une clause SELECT dans 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.
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é. Cette fonction se comporte comme une clause ORDER BY dans 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é. Cette fonction se comporte comme une clause ORDER BY x DESC dans 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. Par exemple, joindre un document person avec person.pets produirait des tuples [person, pet]. Ce comportement est semblable à SelectMany dans .NET LINQ.

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 :

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

Les constructions JavaScript suivantes ne sont pas optimisées pour les index Azure Cosmos DB :

  • Flux de contrôle : if for while
  • Appels de fonction

Pour plus d’informations, consultez la documentation JavaScript Azure Cosmos DB côté serveur.

Aide-mémoire SQL vers JavaScript

Le tableau suivant présente différentes requêtes SQL et les requêtes JavaScript correspondantes. Comme pour les requêtes SQL, les propriétés (par exemple, item.id) respectent la casse.

Remarque

__ (trait de soulignement double) est un alias pour getContext().getCollection() lors de l’utilisation de l’API de requête JavaScript.

SQL API de requête JavaScript Description
SELECT *
FROM docs		 __.map(function(doc) {
    return doc;
});		 Renvoie tous les documents (paginés avec jeton de continuation) tels quels.
SELECT
   docs.id,
   docs.message AS msg,
   docs.actions
FROM docs		 __.map(function(doc) {
    return {
        id: doc.id,
        msg: doc.message,
        actions:doc.actions
    };
});		 Projette l’ID, le message (alias msg) et l’action de tous les documents.
SELECT *
FROM docs
WHERE
   docs.id="X998_Y998"		 __.filter(function(doc) {
    return doc.id ==="X998_Y998";
});		 Requêtes pour les documents avec le prédicat : id = "X998_Y998".
SELECT *
FROM docs
WHERE
   ARRAY_CONTAINS(docs.Tags, 123)		 __.filter(function(x) {
    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.
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();		 Interroge les documents avec un prédicat, id = "X998_Y998", puis projette l’ID et le message (alias 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()		 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.

Étapes suivantes

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 :