Query Documents

Article
02/24/2022

You can query arbitrary json documents in a collection by performing a post against the “colls” resource in Cosmos DB. The sql syntax of Cosmos DB provides hierarchical, relational, and spatial query operators to query and project documents. For more information on querying resources in Cosmos DB, see querying resources.

Request

Method	Request URI	Description
post	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs	note that the {databaseaccount} is the name of the Cosmos DB account created under your subscription. the {db-id} value is the user generated name/id of the database, not the system generated id (rid). the {coll-id} value is the name of the collection.

Headers

See Common Azure Cosmos DB REST request headers for headers that are used by all Cosmos DB requests.

Header	Required	Type	Description
x-ms-documentdb-isquery	Required	Boolean	Must be set to True indicating that the POST is a query.
Content-Type	Required	String	A string that must be set to application/query+json.
x-ms-max-item-count	Optional	Number	An integer indicating the maximum number of items to be returned per page. Queries will return no more than the specified number of items per page, but could be fewer depending on the collection performance tier and their sizes. An x-ms-max-item-count of -1 can be specified to let the service determine the optimal item count. It's the recommended configuration value for x-ms-max-item-count.
x-ms-continuation	Optional	String	A string token returned for queries and read-feed operations if there are more results to be read. Clients can retrieve the next page of results by resubmitting the request with the x-ms-continuation request header set to this value.
x-ms-documentdb-query-enablecrosspartition	Optional	Boolean	If the collection is partitioned, this must be set to True to allow execution across multiple partitions. Queries that filter against a single partition key, or against single-partitioned collections don't need to set the header.
x-ms-consistency-level	Optional	String	This is the consistency level override. The valid values are: Strong, Bounded, Session, or Eventual (in order of strongest to weakest). The override must be the same or weaker than the account’s configured consistency level.
x-ms-session-token	Optional	String	A string token used with session level consistency. Clients must echo the latest read value of this header during read requests for session consistency.

Important

For the Content-Type header do NOT include the charset (i.e. “application/query+json; charset-utf-8”). The header must be exactly as shown above.

Body

Property	Required	Type	Description
query	Required	String	Contains the SQL query text. For grammar, see SQL Grammar.
parameters	Required	Array	An array of parameter values for the query.

{  
  "query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",  
  "parameters": [  
    {  
      "name": "@id",  
      "value": "AndersenFamily"  
    },  
    {  
      "name": "@city",  
      "value": "Seattle"  
    }  
  ]  
}

Response

Returns an array of documents that match the requested query.

Headers

See Common Azure Cosmos DB REST response headers for headers that are returned by all Cosmos DB responses. The important response headers are:

Property	Type	Description
x-ms-continuation	String	Returns a token to fetch more results from the operation. The client can resubmit the request with the x-ms-continuation request header containing this value to resume execution.
x-ms-request-charge	Number	The number of request units consumed by the operation.

Status codes

The following table lists common status codes returned by this operation. For a full list of status codes, see HTTP Status Codes.

HTTP status code	Description
200 OK	The operation was successful.
400 Bad Request	The specified request was specified with an incorrect SQL syntax, or missing required headers.

Body

Property	Description
_rid	This is the system generated resource ID for the collection where the documents reside.
_count	This is the number of documents returned by the list operation.
Documents	The array of documents returned by the operation.

Properties of Document

Property	Description
id	This is the unique name that identifies the document, i.e. no two documents can share the same id. The id must not exceed 255 characters.
<custom>	Any user-defined JSON.
_rid	This is a system generated property. The resource ID (_rid) is a unique identifier that is also hierarchical per the resource stack on the resource model. It is used internally for placement and navigation of the document resource.
_ts	This is a system generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.
_self	This is a system generated property. It is the unique addressable URI for the resource.
_etag	This is a system generated property that specifies the resource etag required for optimistic concurrency control.
_attachments	This is a system generated property that specifies the addressable path for the attachments resource.

{  
  "_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  
}

Example

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/"  
}

Query Documents

Request

Headers

Body

Response

Headers

Status codes

Body

Example

See Also

Additional resources