Eseguire query sui documenti
È possibile eseguire query su documenti json arbitrari in una raccolta eseguendo un post sulla risorsa "colls" in Cosmos DB. La sintassi sql di Cosmos DB fornisce operatori di query gerarchici, relazionali e spaziali per eseguire query e progetti. Per altre informazioni sull'esecuzione di query sulle risorse in Cosmos DB, vedere query sulle risorse.
Richiesta
| Metodo | URI richiesta | Descrizione |
|---|---|---|
| post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | si noti che {databaseaccount} è il nome dell'account Cosmos DB creato nella sottoscrizione. il valore {db-id} è il nome/id generato dall'utente del database, non l'ID generato dal sistema (rid). il valore {coll-id} è il nome della raccolta. |
Intestazioni
Vedere Intestazioni di richiesta REST di Azure Cosmos DB comuni per le intestazioni usate da tutte le richieste di Cosmos DB.
| Intestazione | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|
| x-ms-documentdb-isquery | Necessario | Boolean | Deve essere impostato su True che indica che post è una query. |
| Content-Type | Necessario | string | Stringa che deve essere impostata su application/query+json. |
| x-ms-max-item-count | Facoltativo | Number | Intero che indica il numero massimo di elementi da restituire per pagina. Le query restituiranno non più del numero specificato di elementi per pagina, ma potrebbero essere inferiori a seconda del livello di prestazioni della raccolta e delle relative dimensioni. È possibile specificare un numero x-ms-max-item-count di -1 per consentire al servizio di determinare il conteggio ottimale degli elementi. È il valore di configurazione consigliato per x-ms-max-item-count. |
| x-ms-continuation | Facoltativo | String | Un token di stringa restituito per le query e le operazioni di lettura-feed se sono presenti altri risultati da leggere. I client possono recuperare la pagina successiva dei risultati inviando nuovamente la richiesta con l'intestazione della richiesta x-ms-continuazione impostata su questo valore. |
| x-ms-documentdb-query-enablecrosspartition | Facoltativo | Boolean | Se la raccolta è partizionata, questa operazione deve essere impostata su True per consentire l'esecuzione tra più partizioni. Le query che filtrano su una singola chiave di partizione o su raccolte partizionate singole non devono impostare l'intestazione. |
| x-ms-consistency-level | Facoltativo | String | Questo è l'override del livello di coerenza. I valori validi sono: Strong, Bounded, Session o Eventual (in ordine di più forte a più debole). L'override deve essere uguale o più debole del livello di coerenza configurato dell'account. |
| x-ms-session-token | Facoltativo | String | Token stringa usato con coerenza a livello di sessione. I client devono eco del valore di lettura più recente di questa intestazione durante le richieste di lettura per la coerenza della sessione. |
Importante
Per l'intestazione non includere il Content-Type charset (ad esempio "application/query+json; charset-utf-8"). L'intestazione deve essere esattamente come illustrato sopra.
Corpo
| Proprietà | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|
| query | Necessario | string | Contiene il testo della query SQL. Per la grammatica, vedere Grammatica SQL. |
| parameters | Necessario | Array | Matrice di valori dei parametri per la query. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
Risposta
Restituisce una matrice di documenti che corrispondono alla query richiesta.
Intestazioni
Vedere Intestazioni di risposta REST di Azure Cosmos DB comuni per le intestazioni restituite da tutte le risposte di Cosmos DB. Le intestazioni di risposta importanti sono:
| Proprietà | Type | Descrizione |
|---|---|---|
| x-ms-continuation | string | Restituisce un token per recuperare altri risultati dall'operazione. Il client può inviare nuovamente la richiesta con l'intestazione della richiesta x-ms-continuazione contenente questo valore per riprendere l'esecuzione. |
| x-ms-request-charge | Number | Numero di unità di richiesta usate dall'operazione. |
Codici di stato
La seguente tabella elenca i codici di stato comuni restituiti da questa operazione. Per un elenco completo dei codici di stato, vedere Codici di stato HTTP.
| Codice di stato HTTP | Descrizione |
|---|---|
| 200 - OK | L'operazione è stata completata. |
| 400 - Richiesta non valida | Nella richiesta specificata è stata usata una sintassi SQL non corretta o mancano intestazioni obbligatorie. |
Corpo
| Proprietà | Descrizione |
|---|---|
| _liberarsi | ID della risorsa generato dal sistema per la raccolta in cui si trova il documento. |
| _Conteggio | Numero di documenti restituiti dall'operazione List. |
| Documents (Documenti) | Matrice di documenti restituiti dall'operazione. |
Proprietà del documento
| Proprietà | Descrizione |
|---|---|
| id | Si tratta del nome univoco che identifica il documento, ovvero nessun documento può condividere lo stesso ID. L'ID non deve superare i 255 caratteri. |
| <custom> | Qualsiasi JSON definito dall'utente. |
| _rid | Si tratta di una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco gerarchico anche per ogni stack di risorse nel modello di risorse. Viene usato internamente per il posizionamento e l'esplorazione della risorsa documento. |
| _Ts | Proprietà generata dal sistema. Indica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp. |
| _stesso | Proprietà generata dal sistema. URI indirizzabile univoco per la risorsa. |
| _Etag | Si tratta di una proprietà generata dal sistema che specifica l'etag della risorsa necessaria per il controllo della concorrenza ottimistica. |
| _Allegati | Proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa degli allegati. |
{
"_rid": "1KtjAImkcgw=",
"Documents": [
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}
],
"_count": 1
}
Esempio
POST https://querydemo.documents.azure.com/dbs/1KtjAA==/colls/1KtjAImkcgw=/docs HTTP/1.1
x-ms-continuation:
x-ms-documentdb-isquery: True
x-ms-documentdb-query-enablecrosspartition: True
x-ms-date: Tue, 29 Mar 2016 02:28:32 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3drOlOhFh9plfC0ggZfmHtS3XepVitiIRsd6i1d9PnuW8%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Content-Type: application/query+json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=604; x-ms-session-token=604
Content-Length: 170
Expect: 100-continue
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
HTTP/1.1 201 Created
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT
etag: "00003200-0000-0000-0000-56f9e84d0000"
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb/colls/testcoll
x-ms-quorum-acked-lsn: 602
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 12.38
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668
x-ms-session-token: 0:603
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Tue, 29 Mar 2016 02:28:30 GMT
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}