API di query JavaScript in Azure Cosmos DBJavaScript query API in Azure Cosmos DB

Oltre a eseguire query usando L'API SQL di Azure Cosmos DB, l'SDK di Cosmos DB lato server consente di eseguire query ottimizzate tramite un'interfaccia 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. Non è necessario conoscere il linguaggio SQL per usare questa interfaccia JavaScript.You don't have to be aware of the SQL language to use this JavaScript interface. L'API di query JavaScript consente di creare query a livello di programmazione passando funzioni di predicato in una sequenza di chiamate di funzione, con una sintassi familiare alle librerie JavaScript predefinite e integrate della matrice ECMAScript5 come 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. Le query vengono analizzate dal runtime JavaScript ed eseguite in modo efficiente usando gli indici di Azure Cosmos DB.Queries are parsed by the JavaScript runtime and efficiently executed using Azure Cosmos DB indices.

Funzioni JavaScript supportateSupported JavaScript functions

FunzioneFunction DescrizioneDescription
chain() ... .value([callback] [, options]) Avvia una chiamata concatenata che deve terminare con value().Starts a chained call that must be terminated with value().
filter(predicateFunction [, options] [, callback]) Filtra l'input usando una funzione di predicato che restituisce true o false per includere o escludere i documenti di input dal set risultante.Filters the input using a predicate function that returns true/false in order to filter in/out input documents into the resulting set. Il comportamento di questa funzione è simile a quello di una clausola WHERE in SQL.This function behaves similar to a WHERE clause in SQL.
flatten([isShallow] [, options] [, callback]) Combina e rende flat le matrici da ogni elemento di input in un'unica matrice.Combines and flattens arrays from each input item into a single array. Il comportamento di questa funzione è simile a quello di SelectMany in LINQ.This function behaves similar to SelectMany in LINQ.
map(transformationFunction [, options] [, callback]) Applica una proiezione a partire da una funzione di trasformazione che esegue il mapping di ogni elemento di input a un valore o oggetto JavaScript.Applies a projection given a transformation function that maps each input item to a JavaScript object or value. Il comportamento di questa funzione è simile a quello di una clausola SELECT in SQL.This function behaves similar to a SELECT clause in SQL.
pluck([propertyName] [, options] [, callback]) Questa funzione è un collegamento a una mappa che estrae il valore di una singola proprietà da ogni elemento di input.This function is a shortcut for a map that extracts the value of a single property from each input item.
sortBy([predicate] [, options] [, callback]) Produce un nuovo set di documenti ordinandoli nel flusso di documenti di input in ordine crescente usando il predicato specificato.Produces a new set of documents by sorting the documents in the input document stream in ascending order by using the given predicate. Il comportamento di questa funzione è simile a quello di una clausola ORDER BY in SQL.This function behaves similar to an ORDER BY clause in SQL.
sortByDescending([predicate] [, options] [, callback]) Produce un nuovo set di documenti ordinandoli nel flusso di documenti di input in ordine decrescente usando il predicato specificato.Produces a new set of documents by sorting the documents in the input document stream in descending order using the given predicate. Il comportamento di questa funzione è simile a quello di una clausola ORDER BY x DESC in SQL.This function behaves similar to an ORDER BY x DESC clause in SQL.
unwind(collectionSelector, [resultSelector], [options], [callback]) Esegue un self join con inner array e aggiunge i risultati da entrambi i lati come di tuple alla proiezione dei risultati.Performs a self-join with inner array and adds results from both sides as tuples to the result projection. Ad esempio, l'aggiunta di un documento Person con person.pets produrrebbe tuple [person, pet].For instance, joining a person document with person.pets would produce [person, pet] tuples. Il comportamento è simile a quello di SelectMany in .NET LINK.This is similar to SelectMany in .NET LINK.

Quando inclusi all'interno delle funzioni predicato e/o selettore, i seguenti costrutti JavaScript vengono automaticamente ottimizzati per l'esecuzione diretta sugli indici di 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:

  • Operatori semplici: = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~Simple operators: = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~
  • Valori letterali, incluso il valore letterale dell'oggetto: {}Literals, including the object literal: {}
  • var, returnvar, return

I seguenti costrutti JavaScript non vengono ottimizzati per gli indici di Azure Cosmos DB:The following JavaScript constructs do not get optimized for Azure Cosmos DB indices:

  • Flusso di controllo (ad esempio, if, for, while)Control flow (for example, if, for, while)
  • Chiamate di funzioneFunction calls

Per altre informazioni, vedere la documentazione relativa a JavaScript lato server di Azure Cosmos DB.For more information, see the Cosmos DB Server Side JavaScript Documentation.

Foglio riassuntivo di SQL a JavaScriptSQL to JavaScript cheat sheet

Nella tabella seguente vengono presentate varie query SQL e le query JavaScript corrispondenti.The following table presents various SQL queries and the corresponding JavaScript queries. Come le query SQL, le proprietà (ad esempio item.id) fanno distinzione tra maiuscole e minuscole.As with SQL queries, properties (for example, item.id) are case-sensitive.

Nota

__ (doppio carattere di sottolineatura) è un alias per getContext().getCollection() quando si usa l'API di query JavaScript.__ (double-underscore) is an alias to getContext().getCollection() when using the JavaScript query API.

SQLSQL API di query JavaScriptJavaScript Query API DescrizioneDescription
SELECT *SELECT *
FROM docsFROM docs
.map(function(doc) {.map(function(doc) {
    return doc;    return doc;
});});
Viene restituita così com'è in tutti i documenti, impaginati con token di continuazione.Results in all documents (paginated with continuation token) as is.
SELEZIONASELECT
   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
    };    };
});});
Proietta l'ID, il messaggio (con aliasing effettuato a msg) e l'azione da tutti i documenti.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";
});});
Esegue una query sui documenti con il predicato: 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) > -1;    return x.Tags && x.Tags.indexOf(123) > -1;
});});
Esegue una query sui documenti che hanno una proprietà Tags e Tags è una matrice che contiene il valore 123.Queries for documents that have a Tags property and Tags is an array containing the value 123.
SELEZIONASELECT
   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();
Esegue una query sui documenti con un predicato id = "X998_Y998" e quindi proietta l'ID e il messaggio (con aliasing effettuato a 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 i documenti che hanno la proprietà di matrice Tags, ordina i documenti risultanti in base alla proprietà di sistema timestamp _ts e quindi proietta e appiattisce la matrice 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.

Passaggi successiviNext steps

Altre informazioni su come scrivere e usare stored procedure, trigger e funzioni definite dall'utente in Azure Cosmos DB:Learn more concepts and how-to write and use stored procedures, triggers, and user-defined functions in Azure Cosmos DB: