Understanding Partitioning in Azure Cosmos DB

Understanding Partitioning in Azure Cosmos DB

Azure Cosmos DB is a globally distributed, multi-model database service designed for scalable and high-performance modern applications. It delivers latency in the single-digit milliseconds, guarantees high availability with multi-homing capabilities, and provides five well-defined consistency models. One of the key features that enable Azure Cosmos DB to provide this level of performance, scalability, and global distribution is partitioning.

What is Partitioning?

Partitioning is a method of dividing a large dataset and distributing it across many systems, allowing for parallel transactions, queries, and analytics. In the context of Azure Cosmos DB, partitioning allows the database to scale indefinitely by distributing data and throughput across multiple partitions.

Why is Partitioning Important?

Partitioning plays a crucial role in achieving and maintaining high performance in a distributed database system like Azure Cosmos DB. It allows the database to perform operations on multiple partitions simultaneously, thereby increasing throughput. It also enables the database to store more data than would fit on a single machine by splitting the data across multiple machines.

How Does Azure Cosmos DB Partition Data?

Azure Cosmos DB uses a two-level partitioning scheme: physical and logical partitioning.

Physical Partitioning

Physical partitioning is the first level of partitioning in Azure Cosmos DB. The service automatically manages the number of physical partitions to accommodate storage growth and throughput. Each physical partition is a fixed amount of SSD-based storage combined with a variable amount of CPU and memory resources.

A physical partition can host one or more logical partitions, up to the physical partition’s storage limit. The number of physical partitions in an Azure Cosmos DB container depends on the following factors:

  • The amount of data stored in the container: Each physical partition can store up to 50 GB of data.
  • The throughput provisioned for the container: Each physical partition can provide up to 10,000 Request Units per second (RU/s).

Logical Partitioning

Logical partitioning is the second level of partitioning in Azure Cosmos DB. When you create a container in an Azure Cosmos DB database, you specify a partition key. The partition key is a property in the items stored in the container. Azure Cosmos DB hashes the partition key value, resulting in a partition key range, and uses this range to determine which items belong to each logical partition.

All items with the same partition key belong to the same logical partition. This means that an item’s partition key determines the item’s logical partition. The partition key is immutable, i.e., it cannot be changed once it has been set.

Choosing the Right Partition Key

Choosing the right partition key is crucial for maintaining a balanced distribution of data and request volume across all partitions. An ideal partition key is one that appears frequently as a filter in your queries and has a large number of distinct values. This allows the data and throughput to be distributed evenly across all physical partitions, maximizing the efficiency and performance of the database.

Here are some tips for choosing a good partition key:

  • High Cardinality: Choose a partition key that has a large number of distinct values. High cardinality ensures that data is distributed evenly across all partitions.
  • Even Access Pattern: Choose a partition key that is used frequently in your queries. This ensures that the throughput is distributed evenly across all partitions.
  • Size of Data: Consider the size of data that shares the same partition key value. The total data for a single partition key value must be less than 20 GB.

Understanding Partitioning in Queries

When a query is run against Azure Cosmos DB, it can be served by a single partition or multiple partitions, depending on the nature of the query.

  • Single Partition Query: If a query includes a filter on the partition key, it becomes a single partition query. These queries are scoped to a single partition and are therefore more efficient.
  • Cross Partition Query: If a query does not include a filter on the partition key, it is a cross partition query. These queries require more resources as they have to be broadcast to all partitions.


Partitioning is a fundamental aspect of Azure Cosmos DB that enables it to deliver limitless scale, global distribution, and blazing-fast performance. By understanding how partitioning works and how to choose the right partition key, you can harness the full power of Azure Cosmos DB in your applications.

Remember, the key to effective partitioning is choosing a partition key that results in evenly distributed data and request volume across all partitions. This ensures that you can make the most of your provisioned throughput and storage, leading to more efficient and cost-effective operations.

Whether you’re building a new application on Azure Cosmos DB or optimizing an existing one, understanding partitioning can help you design your data model for optimal performance, scalability, and cost-effectiveness. So, dive in, experiment with different partition keys, and see the impact on your application’s performance and scalability. Happy partitioning!