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 "c001": [Order-1, Order-2, Order-3]
Logical Partition "c002": [Order-4, Order-5]
Logical Partition "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 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:

Before: Physical Partition 1 (50 GB, 10,000 RU/s)
  |-- c001 (20 GB)
  |-- c002 (15 GB)
  |-- c003 (15 GB)

After split:
Physical Partition 1a (25 GB, 5,000 RU/s)
  |-- c001 (20 GB)
  |-- c002 (5 GB)

Physical Partition 1b (25 GB, 5,000 RU/s)
  |-- c002 (10 GB)
  |-- c003 (15 GB)

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

Factor	Impact on RU Cost
Item size	Larger items cost more RUs
Property count	More properties to index costs more RUs for writes
Consistency level	Strong reads cost 2x; eventual reads cost less
Query complexity	Filters, aggregations, and JOINs increase cost
Cross-partition queries	Fan out to multiple partitions, higher cost
Indexing	More indexed properties = higher write RU cost

Measuring RU Consumption