Cosmos DB Partitioning and Request Units

Cosmos DB achieves elastic scale through automatic partitioning and measures all operations in Request Units (RUs). Understanding how partitioning works and how RU consumption is calculated is essential for building performant, cost-effective applications.

---

How Partitioning Works

Logical Partitions

A logical partition is a set of items that share the same partition key value. For example, in an e-commerce container with partition key /customerId:

Logical Partition	Items
"c001"	Order-1, Order-2, Order-3
"c002"	Order-4, Order-5
"c003"	Order-6, Order-7, Order-8, Order-9

Constraint	Limit
Max logical partition size	20 GB
Max item size	2 MB (NoSQL API)

Physical Partitions

Cosmos DB automatically maps logical partitions to physical partitions — the actual compute and storage resources:

Physical Partition	Logical Partitions	Size	Throughput
Physical Partition 1	c001, c002	30 GB	3000 RU/s
Physical Partition 2	c003, c004	25 GB	3000 RU/s
Physical Partition 3	c005, c006	20 GB	3000 RU/s

Constraint	Limit
Max physical partition size	50 GB
Max physical partition throughput	10,000 RU/s

You do not manage physical partitions directly — Cosmos DB creates, merges, and splits them automatically based on storage and throughput demands.

Partition Splits

When a physical partition reaches its storage or throughput limit, Cosmos DB automatically splits it into two:

graph TD
  subgraph Before
    B1["Physical Partition 1 (50 GB, 10,000 RU/s)"] --> Bc1["c001 (20 GB)"]
    B1 --> Bc2["c002 (15 GB)"]
    B1 --> Bc3["c003 (15 GB)"]
  end
  subgraph After split
    A1["Physical Partition 1a (25 GB, 5,000 RU/s)"] --> Ac1["c001 (20 GB)"]
    A1 --> Ac2a["c002 (5 GB)"]
    A2["Physical Partition 1b (25 GB, 5,000 RU/s)"] --> Ac2b["c002 (10 GB)"]
    A2 --> Ac3["c003 (15 GB)"]
  end
  Before ==> After

Splits are transparent to your application — no downtime or configuration changes.

---

Choosing a Partition Key

The partition key is the single most important design decision in Cosmos DB. A poor choice leads to hot partitions, throttling, and wasted RU/s.

Good Partition Key Characteristics

Characteristic	Why It Matters
High cardinality	Many distinct values spread data across many partitions
Even distribution	Each value stores roughly the same amount of data
Frequently in queries	Most queries include the partition key, enabling single-partition operations
Grows with data	New values are created as new data arrives

Examples

Scenario	Good Partition Key	Bad Partition Key
Multi-tenant SaaS	/tenantId	/country (low cardinality)
E-commerce orders	/customerId	/status (few values, hot partitions)
IoT telemetry	/deviceId	/date (all today's data in one partition)
Social media posts	/userId	/category (uneven distribution)

Hierarchical Partition Keys

For scenarios where a single property does not provide sufficient cardinality, Cosmos DB supports hierarchical partition keys (up to 3 levels):

Partition Key: /tenantId / /userId / /sessionId

This enables finer-grained distribution while still supporting efficient queries at any level of the hierarchy.

Synthetic Partition Keys

If no single property provides good distribution, you can create a synthetic partition key by combining properties:

{
  "id": "order-001",
  "customerId": "c001",
  "region": "EU",
  "partitionKey": "c001-EU"
}

---

Request Units (RUs) in Depth

Every Cosmos DB operation — reads, writes, queries, stored procedures — consumes Request Units. An RU is a normalised measure that combines CPU, memory, and I/O.

RU Cost Factors