Partitionkey for Cosmosdb

Question

Partitionkey for Cosmosdb

HimanshuSinha 19,637 Microsoft Employee Moderator

We need to change the partition key for our collection in cosmosdb , Just wanted to know how can we do that?

SAI JAGADEESH KUDIPUDI 3,645 Reputation points Microsoft External Staff Moderator

2026-05-15T22:50:53.14+00:00
Hi **HimanshuSinha,**In Azure Cosmos DB, a Partition Key is used to distribute your data across multiple logical partitions so the database can scale efficiently and provide high performance.

When you create a Cosmos DB container, you choose a property (for example /customerId, /userId, or /deviceId) as the partition key. Cosmos DB then groups and stores items that share the same partition key value together.

For example:

{ "id": "1001", "customerId": "CUST01", "name": "John" }

If /customerId is the partition key, all records with "customerId": "CUST01" belong to the same logical partition.

A good partition key should:

Have many unique values (high cardinality)

Distribute data evenly

Avoid “hot partitions”

Match your common query patterns

Choosing the right partition key is very important because it directly impacts:

Scalability

Performance

Request Unit (RU) consumption

Cost optimization

Also note that the partition key cannot be changed after the container is created.

Microsoft documentation references:

Azure Cosmos DB Partitioning Overview

Partitioning and Horizontal Scaling in Azure Cosmos DB

These documents explain logical partitions, physical partitions, best practices, and partition key selection in detail.

Hope this helps. If you have any follow-up questions, please let me know. I would be happy to help.

1 answer

Your answer

SAI JAGADEESH KUDIPUDI 3,645 Reputation points Microsoft External Staff Moderator

2026-05-15T22:50:53.14+00:00

Hi **HimanshuSinha,**In Azure Cosmos DB, a Partition Key is used to distribute your data across multiple logical partitions so the database can scale efficiently and provide high performance.

When you create a Cosmos DB container, you choose a property (for example /customerId, /userId, or /deviceId) as the partition key. Cosmos DB then groups and stores items that share the same partition key value together.

For example:

{ "id": "1001", "customerId": "CUST01", "name": "John" }

If /customerId is the partition key, all records with "customerId": "CUST01" belong to the same logical partition.

A good partition key should:

Have many unique values (high cardinality)

Distribute data evenly

Avoid “hot partitions”

Match your common query patterns

Choosing the right partition key is very important because it directly impacts:

Scalability

Performance

Request Unit (RU) consumption

Cost optimization

Also note that the partition key cannot be changed after the container is created.

Microsoft documentation references:

Azure Cosmos DB Partitioning Overview

Partitioning and Horizontal Scaling in Azure Cosmos DB

These documents explain logical partitions, physical partitions, best practices, and partition key selection in detail.

Hope this helps. If you have any follow-up questions, please let me know. I would be happy to help.

Answer 1

Changing the partition key of an existing Azure Cosmos DB container cannot be done in place. The supported approach is to copy the data into a new container (or another existing container) that has the desired partition key.

Using the Azure portal (NoSQL API, preview feature):

Open the Azure Cosmos DB account in the Azure portal and go to Data Explorer.
Select the container whose partition key needs to be changed.
Go to Scale & Settings → Partition Keys tab.
Select Change to start the partition key change process.
Choose one of the following:
- Create a new destination container with the new partition key definition, or
- Select an existing destination container in the same database that already has the desired partition key.
The portal will start an intra-account container copy job that copies data from the source container to the destination container offline.
Stop all updates to the source container for the entire duration of the copy to maintain data integrity.
After the copy completes, point the application to the new container and, if no longer needed, delete the old container.

Key limitations for this feature:

Supported only for containers with < 1,000,000 RU/s provisioned throughput and < 4 TB of data. For larger containers, contact Microsoft support.
Not supported if the account has capabilities such as Disable local auth or Merge partition enabled.
Only available in specific supported regions.

General design note:

Partition key values are immutable for individual items; an item’s partition key cannot be updated in place. To “move” an item between partitions, create a new item with the new partition key value and delete the old one. For changing the partition key definition for the entire container, use the container copy approach described above.

References: