JavaScript-Abfrage-API in Azure Cosmos DB

  • Artikel

GILT FÜR: NoSQL

Zusätzlich zum Ausführen von Abfragen mithilfe der API für NoSQL in Azure Cosmos DB bietet das serverseitige Azure Cosmos DB-SDK eine JavaScript-Schnittstelle zum Ausführen optimierter Abfragen in gespeicherten Prozeduren und Triggern in Azure Cosmos DB. Für die Verwendung dieser JavaScript-Schnittstelle sind keine SQL-Sprachkenntnisse erforderlich. Mit der JavaScript-Abfrage-API können Sie programmgesteuert Abfragen erstellen, indem Sie unter Verwendung einer Syntax, die mit den integrierten und weit verbreiteten JavaScript-Bibliotheken von ECMAScript5 wie Lodash vergleichbar ist, Prädikatfunktionen an eine Funktionsaufrufsequenz übergeben. Abfragen werden von der JavaScript-Runtime analysiert und unter Verwendung von Azure Cosmos DB-Indizes effizient ausgeführt.

Unterstützte JavaScript-Funktionen

Function Beschreibung
chain() ... .value([callback] [, options]) Startet einen verketteten Aufruf, der auf „value()“ enden muss.
filter(predicateFunction [, options] [, callback]) Filtert die Eingabe mit einer Prädikatfunktion, die „true“/„false“ zurückgibt, um Eingabedokumente für die sich ergebende Gruppe zu filtern. Diese Funktion verhält sich ähnlich wie eine WHERE-Klausel in SQL.
flatten([isShallow] [, options] [, callback]) Kombiniert und vereinfacht Arrays für alle Eingabeelemente zu einem einzelnen Array. Diese Funktion verhält sich ähnlich wie SelectMany in LINQ.
map(transformationFunction [, options] [, callback]) Wendet eine Projektion unter Verwendung einer Transformationsfunktion an, bei der jedes Eingabeelement einem JavaScript-Objekt oder -Wert zugeordnet wird. Diese Funktion verhält sich ähnlich wie eine SELECT-Klausel in SQL.
pluck([propertyName] [, options] [, callback]) Diese Funktion ist eine Abkürzung für eine Zuordnung, mit der der Wert einer einzelnen Eigenschaft aus jedem Eingabeelement extrahiert wird.
sortBy([predicate] [, options] [, callback]) Erzeugt eine neue Gruppe von Dokumenten, indem die Dokumente im Eingabedokument-Datenstrom unter Verwendung des angegebenen Prädikats in aufsteigender Reihenfolge sortiert werden. Diese Funktion verhält sich ähnlich wie eine ORDER BY-Klausel in SQL.
sortByDescending([predicate] [, options] [, callback]) Erzeugt eine neue Gruppe von Dokumenten, indem die Dokumente im Eingabedokument-Datenstrom unter Verwendung des angegebenen Prädikats in absteigender Reihenfolge sortiert werden. Diese Funktion verhält sich ähnlich wie eine ORDER BY X DESC-Klausel in SQL.
unwind(collectionSelector, [resultSelector], [options], [callback]) Führt eine Selbstverknüpfung mit innerem Array aus und fügt Ergebnisse beider Seiten als Tupel der Ergebnisprojektion hinzu. Durch die Verknüpfung eines Personendokuments mit „person.pets“ entstehen also beispielsweise Tupel vom Typ „[Person, Haustier]“. Dies ist mit SelectMany in .NET LINQ vergleichbar.

Bei der Verwendung innerhalb von Prädikat- und/oder Selektorfunktionen werden die folgenden JavaScript-Konstrukte automatisch optimiert, damit sie direkt für Azure Cosmos DB-Indizes ausgeführt werden:

  • Einfache Operatoren: =+-*/%|^&==!====!==<><=>=||&&<<>>>>>~
  • Literale, einschließlich des Objektliterals: {}
  • var, return

Die folgenden JavaScript-Konstrukte werden nicht für Azure Cosmos DB-Indizes optimiert:

  • Ablaufsteuerung: ifforwhile
  • Funktionsaufrufe

Weitere Informationen finden Sie in der Azure Cosmos DB-Dokumentation für serverseitiges JavaScript.

Cheat Sheet für SQL und JavaScript

In der folgenden Tabelle sind verschiedene SQL-Abfragen und die entsprechenden JavaScript-Abfragen aufgeführt. Bei Eigenschaften (etwa item.id) muss genau wie bei SQL-Abfragen die Groß-/Kleinschreibung beachtet werden.

Hinweis

__ (doppelter Unterstrich) ist bei Verwendung der JavaScript-Abfrage-API ein Alias für getContext().getCollection().

SQL JavaScript-Abfrage-API Beschreibung
SELECT *
FROM docs		 __.map(function(doc) {
    return doc;
});		 Alle Dokumente (umgebrochen mit Fortsetzungstoken) bleiben unverändert.
SELECT
   docs.id,
   docs.message AS msg,
   docs.actions
FROM docs		 __.map(function(doc) {
    return {
        id: doc.id,
        msg: doc.message,
        actions:doc.actions
    };
});		 Projiziert die ID, Meldung (Alias für „msg“) und Aktion aus allen Dokumenten.
SELECT *
FROM docs
WHERE
   docs.id="X998_Y998"		 __.filter(function(doc) {
    return doc.id ==="X998_Y998";
});		 Fragt Dokumente mit dem folgenden Prädikat ab: id = "X998_Y998".
SELECT *
FROM docs
WHERE
   ARRAY_CONTAINS(docs.Tags, 123)		 __.filter(function(x) {
    return x.Tags && x.Tags.indexOf(123) > -1;
});		 Fragt Dokumente mit einer Tags-Eigenschaft ab, wobei „Tags“ ein Array mit dem Wert 123 ist.
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();		 Fragt Dokumente mit einem Prädikat, id = "X998_Y998", ab und projiziert anschließend die ID und die Meldung (Alias für „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()		 Filtert nach Dokumenten mit einer Array-Eigenschaft „Tags“, sortiert die resultierenden Dokumente anhand der Zeitstempel-Systemeigenschaft „_ts“ und projiziert und vereinfacht anschließend das Tags-Array.

Nächste Schritte

Machen Sie sich mit weiteren Konzepten und Vorgehensweisen zum Schreiben und Verwenden von gespeicherten Prozeduren, Triggern und benutzerdefinierten Funktionen in Azure Cosmos DB vertraut: