Get Partition key ranges

  • Article

Performing a GET on a specific collection's pkranges child resource retrieves the list of partition key ranges for the collection.

Note

These API reference articles shows how to create resources using the Azure Cosmos DB data plane API. With the data plane API you can configure basic options such as indexing policy, partition keys much like you can with Cosmos DB SDKs. If you require complete feature support for all Azure Cosmos DB resources, we recommend using the Cosmos DB Resource Provider.

Request

Method Request URI Description
GET https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/pkranges Note that the {databaseaccount} is the name of the Azure Cosmos DB account created under your subscription. The {db-id} id of the database and {coll-id} value is the id of the collection.

Headers

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

Body

None.

Response

Returns the list of partition key ranges for the collection.

Headers

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

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.
404 Not Found The collection is not found.

Body

Property Description
id This is the unique name that identifies the collection.
_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 permission 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 representing the resource etag required for optimistic concurrency control.
PartitionKeyRanges This is the list of partition key ranges for the collection. This can be used for incremental readfeed with the x-ms-documentdb-partitionkeyrangeid header.

Properties of PartitionKeyRanges

Property Description
id

The ID for the partition key range. This is a stable and unique ID within each collection.

Can be used to read documents by partition key range.
maxExclusive The maximum partition key hash value for the partition key range. For internal use.
minInclusive The minimum partition key hash value for the partition key range. For internal use.

Example

You can retrieve the Partition Key Ranges by requesting the pkranges resource within a collection. For example the following request retrieves the list of partition key ranges for the serverlogs collection:

    GET https://querydemo.documents.azure.com/dbs/bigdb/colls/serverlogs/pkranges HTTP/1.1
    x-ms.date: 04/20/2021
    authorization: type%3dmaster%26ver%3d1.0%26sig%3dEConYmRgDExu6q%2bZ8GjfUGOH0AcOx%2behkancw3LsGQ8%3d
    x-ms-consistency-level: Session
    x-ms-version: 2016-07-11
    Accept: application/json
    Host: querydemo.documents.azure.com

This request returns the following response containing metadata about the partition key ranges:

    HTTP/1.1 200 Ok
    Content-Type: application/json
    x-ms-item-count: 25
    x-ms-schemaversion: 1.1
    Date: Tue, 15 Nov 2016 07:26:51 GMT

    {
       "_rid":"qYcAAPEvJBQ=",
       "PartitionKeyRanges":[
          {
             "_rid":"qYcAAPEvJBQCAAAAAAAAUA==",
             "id":"0",
             "_etag":"\"00002800-0000-0000-0000-580ac4ea0000\"",
             "minInclusive":"",
             "maxExclusive":"05C1CFFFFFFFF8",
             "_self":"dbs\/qYcAAA==\/colls\/qYcAAPEvJBQ=\/pkranges\/qYcAAPEvJBQCAAAAAAAAUA==\/",
             "_ts":1477100776
          },
          ...
       ],
       "_count": 25
    }

See Also