Cosmos DB Partitioning Strategies

Partitioning is the mechanism by which Cosmos DB distributes data across multiple physical servers (or nodes) to achieve horizontal scaling. Without partitioning, a single node would become a bottleneck as data grows, limiting storage and throughput. Cosmos DB uses automatic partitioning based on a partition key that you specify when creating a container. This key is a property in each document (e.g., /userId, /deviceId). The partition key value determines which logical partition the document belongs to. Cosmos DB then maps logical partitions to physical partitions, each hosted on a separate node.

When you insert a document, Cosmos DB computes a hash of the partition key value. The hash range is divided into ranges, each assigned to a physical partition. The document is stored on the physical partition responsible for that hash range. All documents with the same partition key value end up in the same logical partition, which resides on a single physical partition. This is crucial: a logical partition cannot span multiple physical partitions. Physical partitions can host multiple logical partitions.

When you provision throughput at the container level (e.g., 400 RU/s), Cosmos DB distributes this throughput across all physical partitions. Each physical partition gets an equal share. For example, if you have 4 physical partitions and 4000 RU/s, each partition gets 1000 RU/s. If one logical partition receives more requests than its host physical partition's share, requests get throttled (HTTP 429).

Queries that specify the partition key in the WHERE clause (e.g., WHERE userId = '123') are point queries and are routed to a single physical partition, costing minimal RUs. Queries without the partition key are cross-partition queries and must fan out to all physical partitions, increasing RU cost and latency.

Once a container is created, you cannot change the partition key. To use a different key, you must create a new container and migrate data using Azure Data Factory or change feed. This is a common exam trap: candidates think you can update it later.

If your natural data doesn't have a high-cardinality key, you can create a synthetic key by concatenating multiple properties. For example, /userId + /date (e.g., user123_2023-01-01). This increases cardinality and spreads writes evenly. However, it complicates queries because you must know the full key.

var container = await database.CreateContainerIfNotExistsAsync(
    id: "users",
    partitionKeyPath: "/userId",
    throughput: 400);

az cosmosdb sql container create \
    --resource-group myGroup \
    --account-name myAccount \
    --database-name myDB \
    --name users \
    --partition-key-path "/userId" \
    --throughput 400

A company stores customer orders in Cosmos DB. Initially, they used /customerId as the partition key. This worked well because each customer has many orders, and cardinality is high. However, they noticed that when a VIP customer placed many orders simultaneously (e.g., during a flash sale), the partition for that customer became a hot spot, throttling requests. They mitigated by using a synthetic key /customerId_orderDate to spread writes across multiple logical partitions per customer. Queries that need all orders for a customer now require a cross-partition query, but the trade-off is acceptable for write-heavy workloads. They also set up autoscale throughput to handle spikes.

An IoT company ingests sensor readings from millions of devices. They chose /deviceId as the partition key, which distributes data evenly because each device sends data independently. However, they also need to query data across all devices for a specific time range. Without the partition key in queries, they face cross-partition queries that are costly. To optimize, they use a secondary index on timestamp and run queries that include deviceId when possible. For global analytics, they use Azure Synapse Link to run analytical queries without impacting transactional throughput.

A SaaS provider stores tenant data in a single Cosmos DB container. They use /tenantId as the partition key. This ensures that all data for a tenant is in one logical partition, enabling transactional stored procedures within a tenant. However, a large tenant's data grew to 18 GB, approaching the 20 GB limit. They had to split the tenant across multiple logical partitions by using a composite key /tenantId_entityType. This required application changes to handle cross-partition transactions. They also faced throttling when the large tenant consumed more than its physical partition's share of throughput. They solved it by increasing provisioned throughput and using autoscale.

A common mistake is choosing a partition key with low cardinality, such as /status with values 'active' and 'inactive'. This results in only two logical partitions, each potentially huge, and all writes go to one partition (e.g., new active records). This causes severe throttling. Another mistake is using a monotonically increasing value like a timestamp as the partition key, which creates a hot partition for recent data. The fix is to use a synthetic key that includes a hash or random suffix to distribute writes.