ドキュメントに対するクエリを実行する

Cosmos DB の "colls" リソースに対して投稿を実行することで、コレクション内の任意の json ドキュメントに対してクエリを実行できます。 Cosmos DB の sql 構文は、ドキュメントのクエリとプロジェクトを実行するための階層型、リレーショナル型、および空間型のクエリ演算子を提供します。 Cosmos DB のリソースに対するクエリの詳細については、「リソースのクエリ」を参照してください。

Request

Method	要求 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 要求ヘッダー」を参照してください。

ヘッダー	必須	Type	Description
x-ms-documentdb-isquery	必須	Boolean	POST がクエリであることを示す True に設定する必要があります。
Content-Type	必須	String	application/query+json に設定する必要がある文字列。
x-ms-max-item-count	省略可能	Number	ページごとに返されるアイテムの最大数を示す整数。 クエリは、1 ページあたり指定された数以下のアイテムを返しますが、コレクションのパフォーマンスレベルとそのサイズによっては少なくなる可能性があります。 x-ms-max-item-count -1 を指定して、サービスが最適な項目数を判断できるようにします。 これは、x-ms-max-item-count の推奨される構成値です。
x-ms-continuation	省略可能	String	読み取る結果が多い場合は、クエリと読み取りフィード操作に対して返される文字列トークン。 クライアントは、x-ms-continuation 要求ヘッダーをこの値に設定して要求を再送信することで、結果の次のページを取得できます。
x-ms-documentdb-query-enablecrosspartition	省略可能	Boolean	コレクションがパーティション分割されている場合、複数のパーティション間での実行を許可するには、これを True に設定する必要があります。 単一のパーティション キーまたは単一パーティションコレクションに対してフィルター処理するクエリでは、ヘッダーを設定する必要はありません。
x-ms-consistency-level	省略可能	String	これは、オーバーライド後の一貫性レベルです。 有効な値は、Strong、Bounded、Session、または Eventual (最も強いものから弱い順) です。 オーバーライドは、アカウントの構成済みの整合性レベルと同じか弱い必要があります。
x-ms-session-token	省略可能	String	セッション レベルの整合性で使用される文字列トークン。 クライアントは、セッション整合性の読み取り要求中に、このヘッダーの最新の読み取り値をエコーする必要があります。

重要

ヘッダーには Content-Type 、charset を含めないでください (つまり、"application/query+json;charset-utf-8")。 ヘッダーは、上に示したとおりである必要があります。

Body

プロパティ	必須	Type	Description
query	必須	String	SQL クエリ テキストを格納します。 文法については、「 SQL 文法」を参照してください。
parameters	必須	Array	クエリのパラメーター値の配列。

{  
  "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 応答ヘッダー 」を参照してください。 重要な応答ヘッダーは次のとおりです。

プロパティ	Type	Description
x-ms-continuation	String	操作からより多くの結果をフェッチするトークンを返します。 クライアントは、この値を含む x-ms-continuation 要求ヘッダーを使用して要求を再送信して、実行を再開できます。
x-ms-request-charge	Number	操作によって消費される要求ユニットの数。

状態コード

次の表に、この操作で返される一般的なステータス コードを示します。 状態コードの完全な一覧については、「 HTTP 状態コード」を参照してください。

HTTP 状態コード	説明
200 OK	操作に成功しました。
400 Bad Request	指定された要求は、誤った SQL 構文を使って指定されているか、または必要なヘッダーが不足しています。

Body

プロパティ	Description
_解消	これはシステムによって生成される、ドキュメントがあるコレクションのリソース ID です。
_カウント	これは、一覧操作によって返されるドキュメントの数です。
ドキュメント	操作で返されるドキュメントの配列。

ドキュメントのプロパティ

プロパティ	説明
id	これはドキュメントを識別する一意の名前です。つまり、2 つのドキュメントで同じ 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/"  
}  
  

参照

• Azure Cosmos DB
• Azure Cosmos DB SQL API
• Azure Cosmos DB SQL API SDK
• .NET サンプルからの REST