你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
查询文档
可以通过对 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，而不是系统生成的 id (rid) 。 {coll-id} 值是集合的名称。 |
标头
有关所有 Cosmos DB 请求 使用的标头，请参阅常见的 Azure Cosmos DB REST 请求标头。
| 标头 | 必需 | 类型 | 说明 |
|---|---|---|---|
| x-ms-documentdb-isquery | 必需 | 布尔 | 必须设置为 True，以指示 POST 为查询。 |
| Content-Type | 必须 | 字符串 | 必须设置为 application/query+json 的字符串。 |
| x-ms-max-item-count | 可选 | Number | 一个整数，指示每页返回的最大项数。 查询返回的项数不超过每页指定的项数，但可能会更少，具体取决于集合性能层及其大小。 可以指定 -1 的 x-ms-max-item-count，让服务确定最佳项计数。 这是 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 请不要包含字符集 (即“application/query+json;charset-utf-8“) 。 标头必须完全如上所示。
正文
| 属性 | 必选 | 类型 | 说明 |
|---|---|---|---|
| query | 必须 | 字符串 | 包含 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 | Number | 操作使用的请求单位数。 |
状态代码
下表列出了此操作返回的常见状态代码。 有关状态代码的完整列表，请参阅 HTTP 状态代码。
| HTTP 状态代码 | 说明 |
|---|---|
| 200 正常 | 操作成功。 |
| 400 错误的请求 | 指定的请求使用了错误的 SQL 语法指定，或缺少必需的标头。 |
正文
| 属性 | 说明 |
|---|---|
| _摆脱 | 这是系统为文档所在的集合生成的资源 ID。 |
| _计数 | 这是列出操作返回的文档数。 |
| 文档 | 操作返回的文档数组。 |
文档的属性
| 属性 | 说明 |
|---|---|
| id | 这是标识文档的唯一名称，即没有两个文档可以共享相同的 ID。 ID 不得超过 255 个字符。 |
| <custom> | 任何用户定义的 JSON。 |
| _摆脱 | 这是 系统生成的属性。 资源 ID (_rid) 是一个唯一标识符，也是按资源模型上的资源堆栈分层的标识符。 它在内部用于文档资源的放置和导航。 |
| _ts | 这是系统生成的属性。 它指定资源的上次更新时间戳。 高值是一个时间戳。 |
| _自我 | 这是系统生成的属性。 它是资源的唯一可寻址 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/"
}