Optimizing database performance: Change partition keys of a container in Azure Cosmos DB for NoSQL API (preview)

Richa Gaur

Partitioning is a key concept in Azure Cosmos DB, a fully managed, globally distributed, multi-model database service that offers unlimited scalability and low latency. By distributing data across multiple physical partitions based on the partition key(s), Azure Cosmos DB optimizes data access and distribution, profoundly impacting database performance and cost. Therefore, choosing the right partition key is paramount to achieving the right performance and cost.

Challenges with partition keys

Choosing the right partition key is not always easy. Sometimes, the partition key that is initially chosen may not be optimal for the query patterns or the data distribution as the application evolves over time. This can lead to issues such as:

  • Hot partitions, which are partitions that receive more requests than others and can cause throttling and/or high costs.
  • Cross-partition queries, which are queries that span multiple partitions and can have higher latency and costs than queries that target a single partition.

In such cases, changing the partition key may be necessary to optimize the performance and cost of the database.

In this blog post, we will introduce a new feature in the Azure Portal that allows changing the partition key of a container in Azure Cosmos DB easily with a few clicks. This feature uses the container copy API in the background, which copies the data from the source container to the destination container.

How partition key change rescues

Changing the partition key of a container in Azure Cosmos DB is not a trivial operation. It requires creating a new container with the desired partition key and copying the data from the existing container to the new one using multiple disparate tools. This process can take time and incur additional costs depending on the size and throughput of the data.

To make this process easier and more convenient, the Azure Portal provides a new feature that allows changing the partition key of a container with a few clicks.

Image cosmosdb change pk

After clicking on the change button, user needs to either create a new container or select an existing one from the same database. If user creates a new container, then all configurations except partition keys and unique keys are replicated from the source container to the new destination container.

Image cosmosdb change pk create container

The portal then uses the container copy API in the background, which copies the data from the source container to the destination container easily without any manual intervention.

Monitoring progress

The user can monitor the progress and status of the copy operation in the portal and cancel it if needed. Once the copy is completed, the user can switch the application to use the new container with the updated partition key and delete the old one.

Image change pk monitoring

Important considerations

While this feature can be very useful, some things to keep in mind before using it are:

  • No writes or deletes should be performed on the source container while the copy job is in progress to ensure the integrity of the data being copied.
  • The copy operation may fail due to various reasons, such as network issues, throttling, or validation errors. The user should check the status and error messages in the portal and retry the change partition key process if needed.
  • The user is responsible for switching the application to use the new container once the copy is completed and deleting the old container if not needed.

Next Steps

With the ability to change partition keys in Azure Cosmos DB, users can adapt and optimize their database structures with ease. This feature empowers users to navigate the evolving landscape of database management, unlocking enhanced performance and cost efficiency.

If you have any questions or comments, please feel free to leave them below or contact us through the support channels. Thank you for reading and happy coding!

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless distributed database for modern app development, with SLA-backed speed and availability, automatic and instant scalability, and support for open-source PostgreSQL, MongoDB, and Apache Cassandra. Try Azure Cosmos DB for free here. To stay in the loop on Azure Cosmos DB updates, follow us on XYouTube, and LinkedIn.


Leave a comment

  • Lingling MaMicrosoft employee 0

    The container data copy job should be based on changefeed, can I stop the source write/delete traffic near the end of copy job, then wait for the copy job complete. Through this the downtime for customers can be reduced to few minutes.

    • Richa GaurMicrosoft employee 0

      Hi Lingling Ma,

      Partiton key change uses latest version change feed mode which doesn’t capture deletes and intermediate updates. For your use-case, if there are only new writes, then you can stop the writes at the end of copy job and wait for it to complete.

Feedback usabilla icon