JavaScript-Abfrage-API in Azure Cosmos DBJavaScript query API in Azure Cosmos DB

Neben Abfragen über die SQL-API in Azure Cosmos DB können Sie mithilfe des serverseitigen Cosmos DB SDK auch optimierte Abfragen über eine JavaScript-Schnittstelle ausführen.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. Für die Verwendung dieser JavaScript-Schnittstelle sind keine SQL-Sprachkenntnisse erforderlich.You don't have to be aware of the SQL language to use this JavaScript interface. 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.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. Abfragen werden von der JavaScript-Runtime analysiert und unter Verwendung von Azure Cosmos DB-Indizes effizient ausgeführt.Queries are parsed by the JavaScript runtime and efficiently executed using Azure Cosmos DB indices.

Unterstützte JavaScript-FunktionenSupported JavaScript functions

FunctionFunction BeschreibungDescription
chain() ... .value([callback] [, options]) Startet einen verketteten Aufruf, der auf „value()“ enden muss.Starts a chained call that must be terminated with value().
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.Filters the input using a predicate function that returns true/false in order to filter in/out input documents into the resulting set. Diese Funktion verhält sich ähnlich wie eine WHERE-Klausel in SQL.This function behaves similar to a WHERE clause in SQL.
flatten([isShallow] [, options] [, callback]) Kombiniert und vereinfacht Arrays für alle Eingabeelemente zu einem einzelnen Array.Combines and flattens arrays from each input item into a single array. Diese Funktion verhält sich ähnlich wie SelectMany in LINQ.This function behaves similar to 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.Applies a projection given a transformation function that maps each input item to a JavaScript object or value. Diese Funktion verhält sich ähnlich wie eine SELECT-Klausel in SQL.This function behaves similar to a SELECT clause 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.This function is a shortcut for a map that extracts the value of a single property from each input item.
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.Produces a new set of documents by sorting the documents in the input document stream in ascending order by using the given predicate. Diese Funktion verhält sich ähnlich wie eine ORDER BY-Klausel in SQL.This function behaves similar to an ORDER BY clause 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.Produces a new set of documents by sorting the documents in the input document stream in descending order using the given predicate. Diese Funktion verhält sich ähnlich wie eine ORDER BY X DESC-Klausel in SQL.This function behaves similar to an ORDER BY x DESC clause 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.Performs a self-join with inner array and adds results from both sides as tuples to the result projection. Durch die Verknüpfung eines Personendokuments mit „person.pets“ entstehen also beispielsweise Tupel vom Typ „[Person, Haustier]“.For instance, joining a person document with person.pets would produce [person, pet] tuples. Dies ist mit „SelectMany“ in .NET LINK vergleichbar.This is similar to SelectMany in .NET LINK.

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

  • Einfache Operatoren: = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~Simple operators: = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~
  • Literale, einschließlich des Objektliterals: {}Literals, including the object literal: {}
  • var, returnvar, return

Die folgenden JavaScript-Konstrukte werden nicht für Azure Cosmos DB-Indizes optimiert:The following JavaScript constructs do not get optimized for Azure Cosmos DB indices:

  • Ablaufsteuerung (z.B. wenn, für, während)Control flow (for example, if, for, while)
  • FunktionsaufrufeFunction calls

Weitere Informationen finden Sie in der Cosmos DB-Dokumentation für serverseitiges JavaScript.For more information, see the Cosmos DB Server Side JavaScript Documentation.

Cheat Sheet für SQL und JavaScriptSQL to JavaScript cheat sheet

In der folgenden Tabelle sind verschiedene SQL-Abfragen und die entsprechenden JavaScript-Abfragen aufgeführt.The following table presents various SQL queries and the corresponding JavaScript queries. Bei Eigenschaften (etwa „item.id“) muss genau wie bei SQL-Abfragen die Groß-/Kleinschreibung beachtet werden.As with SQL queries, properties (for example, item.id) are case-sensitive.

Hinweis

__ (doppelter Unterstrich) ist bei Verwendung der JavaScript-Abfrage-API ein Alias für getContext().getCollection().__ (double-underscore) is an alias to getContext().getCollection() when using the JavaScript query API.

SQLSQL JavaScript-Abfrage-APIJavaScript Query API BeschreibungDescription
SELECT *SELECT *
FROM docsFROM docs
.map(function(doc) {.map(function(doc) {
    return doc;    return doc;
});});
Alle Dokumente (umgebrochen mit Fortsetzungstoken) bleiben unverändert.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
    };    };
});});
Projiziert die ID, Meldung (Alias für „msg“) und Aktion aus allen Dokumenten.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";
});});
Fragt Dokumente mit dem folgenden Prädikat ab: 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) &amp;gt; -1;    return x.Tags && x.Tags.indexOf(123) > -1;
});});
Fragt Dokumente mit einer Tags-Eigenschaft ab, wobei „Tags“ ein Array mit dem Wert 123 ist.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();
Fragt Dokumente mit einem Prädikat, id = "X998_Y998", ab und projiziert anschließend die ID und die Meldung (Alias für „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()
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.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.

Nächste SchritteNext steps

Machen Sie sich mit weiteren Konzepten und Vorgehensweisen zum Schreiben und Verwenden von gespeicherten Prozeduren, Triggern und benutzerdefinierten Funktionen in Azure Cosmos DB vertraut:Learn more concepts and how-to write and use stored procedures, triggers, and user-defined functions in Azure Cosmos DB: