Query's uitvoeren op documenten
U kunt query's uitvoeren op willekeurige JSON-documenten in een verzameling door een bericht uit te voeren op de resource 'colls' in Cosmos DB. De SQL-syntaxis van Cosmos DB biedt hiërarchische, relationele en ruimtelijke queryoperators voor het uitvoeren van query's en projectdocumenten. Zie Query's uitvoeren op resources voor meer informatie over het uitvoeren van query's op resources in Cosmos DB.
Aanvraag
| Methode | Aanvraag-URI | Beschrijving |
|---|---|---|
| Verzenden | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | Houd er rekening mee dat {databaseaccount} de naam is van het Cosmos DB-account dat is gemaakt onder uw abonnement. de waarde {db-id} is de door de gebruiker gegenereerde naam/id van de database, niet de door het systeem gegenereerde id (rid). de waarde {coll-id} is de naam van de verzameling. |
Kopteksten
Zie Algemene Azure Cosmos DB REST-aanvraagheaders voor headers die worden gebruikt door alle Cosmos DB-aanvragen.
| Header | Vereist | Type | Beschrijving |
|---|---|---|---|
| x-ms-documentdb-isquery | Vereist | Booleaans | Moet worden ingesteld op Waar om aan te geven dat de POST een query is. |
| Content-Type | Vereist | Tekenreeks | Een tekenreeks die moet worden ingesteld op application/query+json. |
| x-ms-max-item-count | Optioneel | Aantal | Een geheel getal dat het maximum aantal items aangeeft dat per pagina moet worden geretourneerd. Query's retourneren niet meer dan het opgegeven aantal items per pagina, maar kunnen minder zijn, afhankelijk van de prestatielaag van de verzameling en hun grootte. Er kan een x-ms-max-item-count van -1 worden opgegeven om de service het optimale aantal items te laten bepalen. Dit is de aanbevolen configuratiewaarde voor x-ms-max-item-count. |
| x-ms-continuation | Optioneel | Tekenreeks | Een tekenreekstoken dat wordt geretourneerd voor query's en leesfeedbewerkingen als er meer resultaten moeten worden gelezen. Clients kunnen de volgende pagina met resultaten ophalen door de aanvraag opnieuw in te dienen met de aanvraagheader x-ms-continuation ingesteld op deze waarde. |
| x-ms-documentdb-query-enablecrosspartition | Optioneel | Booleaans | Als de verzameling is gepartitioneerd, moet deze worden ingesteld op Waar om uitvoering over meerdere partities toe te staan. Query's die filteren op één partitiesleutel of op verzamelingen met één partitie, hoeven de header niet in te stellen. |
| x-ms-consistency-level | Optioneel | Tekenreeks | Dit is de overschrijving van het consistentieniveau. De geldige waarden zijn: Sterk, Gebonden, Sessie of Uiteindelijk (in volgorde van sterk naar zwak). De onderdrukking moet hetzelfde of zwakker zijn dan het geconfigureerde consistentieniveau van het account. |
| x-ms-session-token | Optioneel | Tekenreeks | Een tekenreekstoken dat wordt gebruikt met consistentie op sessieniveau. Clients moeten de meest recente leeswaarde van deze header herhalen tijdens leesaanvragen voor sessieconsistentie. |
Belangrijk
Neem voor de Content-Type header NIET de charset op (d.w.w. 'application/query+json; charset-utf-8"). De header moet precies zijn zoals hierboven wordt weergegeven.
Hoofdtekst
| Eigenschap | Vereist | Type | Beschrijving |
|---|---|---|---|
| Query | Vereist | Tekenreeks | Bevat de SQL-querytekst. Zie SQL-grammatica voor grammatica. |
| parameters | Vereist | Matrix | Een matrix met parameterwaarden voor de query. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
Antwoord
Retourneert een matrix met documenten die overeenkomen met de aangevraagde query.
Kopteksten
Zie Algemene Azure Cosmos DB REST-antwoordheaders voor headers die worden geretourneerd door alle Cosmos DB-antwoorden. De belangrijke antwoordheaders zijn:
| Eigenschap | Type | Beschrijving |
|---|---|---|
| x-ms-continuation | Tekenreeks | Retourneert een token om meer resultaten van de bewerking op te halen. De client kan de aanvraag opnieuw indienen met de aanvraagheader x-ms-continuation die deze waarde bevat om de uitvoering te hervatten. |
| x-ms-request-charge | Aantal | Het aantal aanvraageenheden dat door de bewerking wordt verbruikt. |
Statuscodes
De volgende tabel bevat algemene statuscodes die door deze bewerking worden geretourneerd. Zie HTTP-statuscodes voor een volledige lijst met statuscodes.
| HTTP-statuscode | Beschrijving |
|---|---|
| 200 OK | De bewerking is geslaagd. |
| 400 Ongeldige aanvraag | De opgegeven aanvraag is opgegeven met een onjuiste SQL-syntaxis of ontbrekende vereiste headers. |
Hoofdtekst
| Eigenschap | Beschrijving |
|---|---|
| _Ontdoen | Dit is de door het systeem gegenereerde resource-id voor de verzameling waarin de documenten zich bevinden. |
| _Tellen | Dit is het aantal documenten dat door de lijstbewerking wordt geretourneerd. |
| Documenten | De matrix met documenten die door de bewerking worden geretourneerd. |
Eigenschappen van document
| Eigenschap | Beschrijving |
|---|---|
| id | Dit is de unieke naam waarmee het document wordt aangeduid, d.w.w.v. geen twee documenten kunnen dezelfde id delen. De id mag niet langer zijn dan 255 tekens. |
| <aangepast> | Elke door de gebruiker gedefinieerde JSON. |
| _Ontdoen | Dit is een door het systeem gegenereerde eigenschap. De resource-id (_rid) is een unieke id die ook hiërarchisch is per resourcestack in het resourcemodel. De id wordt intern gebruikt voor het plaatsen van en navigeren naar de documentresource. |
| _Ts | Dit is een door het systeem gegenereerde eigenschap. Hiermee wordt de tijdstempel van de resource voor het laatst bijgewerkt. De waarde is een tijdstempel. |
| _Zelf | Dit is een door het systeem gegenereerde eigenschap. Dit is de unieke adresseerbare URI voor de resource. |
| _etag | Dit is een door het systeem gegenereerde eigenschap die de resource-etag aangeeft die is vereist voor optimistisch gelijktijdigheidsbeheer. |
| _Bijlagen | Dit is een door het systeem gegenereerde eigenschap die het adresseerbare pad voor de bijlagenresource aangeeft. |
{
"_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
}
Voorbeeld
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/"
}