API di query JavaScript in Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL

Oltre a eseguire query usando l'API per NoSQL di Azure Cosmos DB, l'SDK lato server di Azure Cosmos DB offre un'interfaccia JavaScript per eseguire query ottimizzate nelle stored procedure e nei trigger di Azure Cosmos DB. Non è necessario conoscere il linguaggio SQL per usare questa interfaccia JavaScript. L'API di query di JavaScript consente di creare query a livello di programmazione passando funzioni di predicato in una sequenza di chiamate di funzione, con una sintassi simile alle librerie JavaScript predefinite di ECMAScript5 e alle librerie JavaScript più diffuse come Lodash. Le query vengono analizzate dal runtime JavaScript ed eseguite in modo efficiente usando gli indici di Azure Cosmos DB.

Funzioni JavaScript supportate

Funzione Descrizione
chain() ... .value([callback] [, options]) Avvia una chiamata concatenata che deve terminare con 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. Il comportamento di questa funzione è simile a quello di una clausola WHERE in SQL.
flatten([isShallow] [, options] [, callback]) Combina e rende flat le matrici da ogni elemento di input in un'unica matrice. Il comportamento di questa funzione è simile a quello di 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. Il comportamento di questa funzione è simile a quello di una clausola SELECT 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.
sortBy([predicate] [, options] [, callback]) Produce un nuovo set di documenti ordinandoli nel flusso di documenti di input in ordine crescente usando il predicato specificato. Il comportamento di questa funzione è simile a quello di una clausola ORDER BY 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. Il comportamento di questa funzione è simile a quello di una clausola ORDER BY x DESC 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. Ad esempio, l'aggiunta di un documento Person con person.pets produrrebbe tuple [person, pet]. Il comportamento è simile a quello di SelectMany in .NET LINQ.

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:

  • Operatori semplici: =+-*/%|^&==!====!==<><=>=||&&<<>>>>>~
  • Valori letterali, incluso il valore letterale dell'oggetto: {}
  • var, return

I seguenti costrutti JavaScript non vengono ottimizzati per gli indici di Azure Cosmos DB:

  • Flusso di controllo: ifforwhile
  • Chiamate di funzione

Per ottenere altre informazioni, consultare la documentazione relativa a JavaScript lato server di Azure Cosmos DB.

Foglio riassuntivo di SQL a JavaScript

Nella tabella seguente vengono presentate varie query SQL e le query JavaScript corrispondenti. Come per le query SQL, le proprietà ,ad esempio , item.idfanno distinzione tra maiuscole e minuscole.

Nota

__ (doppio carattere di sottolineatura) è un alias per getContext().getCollection() quando si usa l'API di query JavaScript.

SQL API di query JavaScript Descrizione
SELECT *
FROM docs		 __.map(function(doc) {
    return doc;
});		 Viene restituita così com'è in tutti i documenti, impaginati con token di continuazione.
SELECT
   docs.id,
   docs.message AS msg,
   docs.actions
FROM docs		 __.map(function(doc) {
    return {
        id: doc.id,
        msg: doc.message,
        actions:doc.actions
    };
});		 Proietta l'ID, il messaggio (con aliasing effettuato a msg) e l'azione da tutti i documenti.
SELECT *
FROM docs
WHERE
   docs.id="X998_Y998"		 __.filter(function(doc) {
    return doc.id ==="X998_Y998";
});		 Esegue una query sui documenti con il predicato: id = "X998_Y998".
SELECT *
FROM docs
WHERE
   ARRAY_CONTAINS(docs.Tags, 123)		 __.filter(function(x) {
    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.
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();		 Esegue una query sui documenti con un predicato id = "X998_Y998" e quindi proietta l'ID e il messaggio (con aliasing effettuato a 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()		 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.

Passaggi successivi

Altre informazioni su come scrivere e usare stored procedure, trigger e funzioni definite dall'utente in Azure Cosmos DB: