문서 쿼리
Cosmos DB의 "colls" 리소스에 대해 게시물을 수행하여 컬렉션에서 임의의 json 문서를 쿼리할 수 있습니다. Cosmos DB의 sql 구문은 문서를 쿼리하고 프로젝트하는 계층적, 관계형 및 공간 쿼리 연산자를 제공합니다. Cosmos DB에서 리소스를 쿼리하는 방법에 대한 자세한 내용은 리소스 쿼리를 참조하세요.
요청
| 메서드 | 요청 URI | 설명 |
|---|---|---|
| post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | {databaseaccount}는 구독에서 만든 Cosmos DB 계정의 이름입니다. {db-id} 값은 시스템 생성 ID(rid)가 아니라 사용자가 생성한 데이터베이스의 이름/ID입니다. {coll-id} 값은 컬렉션의 이름입니다. |
헤더
모든 Cosmos DB 요청 에서 사용되는 헤더는 일반적인 Azure Cosmos DB REST 요청 헤더를 참조하세요.
| 헤더 | 필수 | 형식 | 설명 |
|---|---|---|---|
| x-ms-documentdb-isquery | 필수 | 부울 | POST가 쿼리임을 나타내는 True로 설정해야 합니다. |
| Content-Type | 필수 | 문자열 | application/query+json으로 설정해야 하는 문자열입니다. |
| x-ms-max-item-count | 선택 사항 | 숫자 | 페이지당 반환할 최대 항목 수를 나타내는 정수입니다. 쿼리는 페이지당 지정된 수의 항목을 반환하지 않지만 컬렉션 성능 계층 및 크기에 따라 더 적을 수 있습니다. 서비스에서 최적의 항목 수를 결정할 수 있도록 x-ms-max-item-count -1을 지정할 수 있습니다. x-ms-max-item-count에 권장되는 구성 값입니다. |
| x-ms-continuation | 선택 사항 | 문자열 | 읽을 결과가 더 있는 경우 쿼리 및 읽기 피드 작업에 대해 반환되는 문자열 토큰입니다. 클라이언트는 x-ms-continuation 요청 헤더가 이 값으로 설정된 요청을 다시 제출하여 결과의 다음 페이지를 검색할 수 있습니다. |
| x-ms-documentdb-query-enablecrosspartition | 선택 사항 | 부울 | 컬렉션이 분할된 경우 여러 파티션에서 실행을 허용하려면 True로 설정해야 합니다. 단일 파티션 키 또는 단일 분할된 컬렉션에 대해 필터링하는 쿼리는 헤더를 설정할 필요가 없습니다. |
| x-ms-consistency-level | 선택 사항 | 문자열 | 일관성 수준 재정의입니다. 유효한 값은 Strong, Bounded, Session 또는 Eventual입니다(가장 강한 값에서 가장 약한 순서로). 재정의는 계정의 구성된 일관성 수준과 동일하거나 약해야 합니다. |
| x-ms-session-token | 선택 사항 | 문자열 | 세션 수준 일관성에 사용되는 문자열 토큰입니다. 클라이언트는 세션 일관성에 대한 읽기 요청 중에 이 헤더의 최신 읽기 값을 에코해야 합니다. |
중요
헤더의 Content-Type 경우 charset(예: "application/query+json; charset-utf-8"). 헤더는 위에 표시된 것과 똑딱해야 합니다.
본문
| 속성 | 필수 | 형식 | 설명 |
|---|---|---|---|
| 쿼리 | 필수 | 문자열 | SQL 쿼리 텍스트를 포함합니다. 문법은 SQL 문법을 참조하세요. |
| parameters | 필수 | 배열 | 쿼리에 대한 매개 변수 값의 배열입니다. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
응답
요청된 쿼리와 일치하는 문서 배열을 반환합니다.
헤더
모든 Cosmos DB 응답 에서 반환되는 헤더는 일반적인 Azure Cosmos DB REST 응답 헤더를 참조하세요. 중요한 응답 헤더는 다음과 같습니다.
| 속성 | 형식 | 설명 |
|---|---|---|
| x-ms-continuation | 문자열 | 작업에서 더 많은 결과를 가져오는 토큰을 반환합니다. 클라이언트는 이 값이 포함된 x-ms-continuation 요청 헤더를 사용하여 요청을 다시 제출하여 실행을 다시 시작할 수 있습니다. |
| x-ms-request-charge | 숫자 | 작업에서 사용하는 요청 단위 수입니다. |
상태 코드
다음 표에는 이 작업에서 반환하는 일반적인 상태 코드가 나열되어 있습니다. 상태 코드의 전체 목록은 HTTP 상태 코드를 참조하세요.
| HTTP 상태 코드 | 설명 |
|---|---|
| 200 정상 | 작업이 완료되었습니다. |
| 400 잘못된 요청 | 지정된 요청이 잘못된 SQL 구문으로 지정되었거나 필수 헤더가 누락되었습니다. |
본문
| 속성 | 설명 |
|---|---|
| _제거 | 문서가 있는 컬렉션의 시스템 생성 리소스 ID입니다. |
| _횟수 | 목록 작업에서 반환하는 문서의 수입니다. |
| 문서 | 작업에서 반환하는 문서의 배열입니다. |
문서의 속성
| 속성 | Description |
|---|---|
| id | 이 이름은 문서를 식별하는 고유한 이름입니다. 즉, 두 문서가 동일한 ID를 공유할 수 없습니다. ID 는 255자를 초과하면 안됩니다. |
| <custom> | 모든 사용자 정의 JSON입니다. |
| _rid | 시스템 생성 속성입니다. 리소스 ID(_rid)는 리소스 모델의 리소스 스택당 계층적인 고유 식별자입니다. 문서 리소스의 배치와 탐색을 위해 내부적으로 사용됩니다. |
| _ts | 시스템 생성 속성으로, 리소스가 마지막으로 업데이트된 시간의 타임스탬프를 지정합니다. 값은 타임스탬프입니다. |
| _self | 시스템 생성 속성으로, 고유한 주소를 지정할 수 있는 리소스의 URI입니다. |
| _etag | 낙관적 동시성 제어에 필요한 리소스 etag 를 지정하는 시스템 생성 속성입니다. |
| _첨부 파일 | 첨부 파일 리소스의 주소 지정 가능한 경로를 지정하는 시스템 생성 속성입니다. |
{
"_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
}
예제
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/"
}