Abfragen von Dokumenten
Sie können beliebige JSON-Dokumente in einer Sammlung abfragen, indem Sie einen Beitrag für die Ressource "colls" in Cosmos DB ausführen. Die SQL-Syntax von Cosmos DB bietet hierarchische, relationale und räumliche Abfrageoperatoren zum Abfragen und Projektieren von Dokumenten. Weitere Informationen zum Abfragen von Ressourcen in Cosmos DB finden Sie unter Abfragen von Ressourcen.
Anforderung
| Methode | Anforderungs-URI | BESCHREIBUNG |
|---|---|---|
| post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | Beachten Sie, dass {databaseaccount} der Name des Cosmos DB-Kontos ist, das unter Ihrem Abonnement erstellt wurde. Der Wert {db-id} ist der vom Benutzer generierte Name/id der Datenbank, nicht die vom System generierte ID (los). der Wert {coll-id} ist der Name der Auflistung. |
Header
Informationen zu Headern, die von allen Cosmos DB-Anforderungen verwendet werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Anforderungsheader .
| Header | Erforderlich | type | BESCHREIBUNG |
|---|---|---|---|
| x-ms-documentdb-isquery | Erforderlich | Boolean | Muss auf True festgelegt werden, was angibt, dass es sich bei der POST um eine Abfrage handelt. |
| Content-Type | Erforderlich | String | Eine Zeichenfolge, die auf application/query+json festgelegt werden muss. |
| x-ms-max-item-count | Optional | Number | Eine ganze Zahl, die die maximale Anzahl von Elementen angibt, die pro Seite zurückgegeben werden sollen. Abfragen geben nicht mehr als die angegebene Anzahl von Elementen pro Seite zurück, können aber je nach Sammlungsleistungsebene und deren Größen weniger sein. Es kann eine x-ms-max-item-count von -1 angegeben werden, damit der Dienst die optimale Elementanzahl bestimmen kann. Dies ist der empfohlene Konfigurationswert für x-ms-max-item-count. |
| x-ms-continuation | Optional | String | Ein Zeichenfolgentoken, das für Abfragen und Lesefeedvorgänge zurückgegeben wird, wenn weitere Ergebnisse gelesen werden müssen. Clients können die nächste Seite der Ergebnisse abrufen, indem sie die Anforderung erneut mit dem Header x-ms-continuation request übermitteln, der auf diesen Wert festgelegt ist. |
| x-ms-documentdb-query-enablecrosspartition | Optional | Boolean | Wenn die Auflistung partitioniert ist, muss dies auf True festgelegt werden, um die Ausführung über mehrere Partitionen hinweg zu ermöglichen. Abfragen, die nach einem einzelnen Partitionsschlüssel oder nach einzelpartitionierten Sammlungen filtern, müssen den Header nicht festlegen. |
| x-ms-consistency-level | Optional | String | Dies ist die Überschreibung der Konsistenzebene. Die gültigen Werte sind: Strong, Bounded, Session oder Eventual (in der Reihenfolge von stärkstem bis schwächstem Wert). Die Überschreibung muss identisch oder schwächer als die konfigurierte Konsistenzebene des Kontos sein. |
| x-ms-session-token | Optional | String | Ein Zeichenfolgentoken, das mit Konsistenz auf Sitzungsebene verwendet wird. Clients müssen den aktuellen Lesewert dieses Headers bei Leseanforderungen für Sitzungskonsistenz wiedergibt. |
Wichtig
Für den Content-Type Header nicht das Zeichenset enthalten (d. h. "application/query+json; charset-utf-8"). Der Header muss genau wie oben dargestellt sein.
Body
| Eigenschaft | Erforderlich | type | BESCHREIBUNG |
|---|---|---|---|
| Frage | Erforderlich | String | Enthält den SQL-Abfragetext. Informationen zur Grammatik finden Sie unter SQL-Grammatik. |
| parameters | Erforderlich | Array | Ein Array von Parameterwerten für die Abfrage. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
Antwort
Gibt ein Array von Dokumenten zurück, die der angeforderten Abfrage entsprechen.
Header
Informationen zu Headern, die von allen Cosmos DB-Antworten zurückgegeben werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Antwortheader . Die wichtigen Antwortheader sind:
| Eigenschaft | type | BESCHREIBUNG |
|---|---|---|
| x-ms-continuation | String | Gibt ein Token zurück, um weitere Ergebnisse aus dem Vorgang abzurufen. Der Client kann die Anforderung erneut mit dem Header x-ms-continuation request übermitteln, der diesen Wert enthält, um die Ausführung fortzusetzen. |
| x-ms-request-charge | Number | Die Anzahl der vom Vorgang verbrauchten Anforderungseinheiten. |
Statuscodes
In der folgenden Tabelle sind die allgemeinen Statuscodes aufgeführt, die von diesem Vorgang zurückgegeben werden. Eine vollständige Liste der status Codes finden Sie unter HTTP-Statuscodes.
| HTTP-Statuscode | BESCHREIBUNG |
|---|---|
| 200 – OK | Der Vorgang wurde durchgeführt. |
| 400 – Ungültige Anforderung | Die angegebene Anforderung wurde mit einer falschen SQL-Syntax oder fehlenden erforderlichen Headern angegeben. |
Body
| Eigenschaft | BESCHREIBUNG |
|---|---|
| _los | Dies ist die vom System generierte Ressourcen-ID für die Auflistung, in der sich die Dokumente befinden. |
| _Count | Dies ist die Anzahl der Dokumente, die vom Auflistungsvorgang zurückgegeben werden. |
| Dokumente | Das Array von Dokumenten, das vom Vorgang zurückgegeben wird. |
Eigenschaften des Dokuments
| Eigenschaft | BESCHREIBUNG |
|---|---|
| id | Dies ist der eindeutige Name, der das Dokument identifiziert, d. h. keine zwei Dokumente können dieselbe ID verwenden. Die ID darf nicht länger als 255 Zeichen sein. |
| <custom> | Beliebiger benutzerdefinierter JSON-Code. |
| _los | Dies ist eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch je nach Ressourcenstapel im Ressourcenmodell hierarchisch ist. Sie wird intern für die Platzierung und Navigation der Dokumentressource verwendet. |
| _Ts | Dies ist eine vom System generierte Eigenschaft. Sie gibt den zuletzt aktualisierten Zeitstempel der Ressource an. Der Wert ist ein Zeitstempel. |
| _Selbst | Dies ist eine vom System generierte Eigenschaft. Es handelt sich um den eindeutigen, adressierbaren URI für die Ressource. |
| _Etag | Dies ist eine vom System generierte Eigenschaft, die das Ressourcen-Etag angibt, das für die Steuerung der optimistischen Parallelität erforderlich ist. |
| _Anlagen | Dies ist eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Anlagenressource angibt. |
{
"_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
}
Beispiel
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/"
}