Logical vs physical partitions: throughput and storage limits
Verdict: A logical partition caps at 20 GB regardless of RU/s. Container throughput divides evenly across physical partitions; each physical partition tops out at 10,000 RU/s provisioned, 5,000 RU/s serverless. Placement is by hash.
| Criterion | Logical partition | Physical partition |
|---|---|---|
| Storage | 20 GB hard ceiling, independent of RU/s or capacity mode | Service-managed, hosts many logical partitions |
| Throughput | Shares its physical partition's RU/s with co-located logical partitions | Gets container RU/s divided evenly across physical partitions |
| Placement | Assigned by hashing the partition key value | Allocated an even slice of the hash key space |
| Ceiling | n/a | 10,000 RU/s provisioned; 5,000 RU/s serverless |
Rules
- Maximum storage per logical partition is 20 GB, independent of provisioned throughput and capacity mode.
- Provisioned throughput divides evenly across physical partitions: 18,000 RU/s over 3 partitions gives each 6,000 RU/s.
- Cosmos DB hashes the partition key value and allocates the hash key space evenly across physical partitions.
- A serverless container's ceiling is 5,000 RU/s per physical partition, so total throughput scales with partition count.
- For a write-heavy workload with no single high-cardinality aligned field, use a synthetic key such as CustomerId + OrderDate to spread writes.
- Never embed a collection that can grow without bound; reference it as separate items keyed by the parent id.
Traps
- Raising RU/s does not raise the 20 GB per-logical-partition ceiling; it is a storage limit, not a throughput one.
- A physical partition's RU/s is shared by all logical partitions mapped to it, not allocated per logical partition.
- A 429 rate below 10% is not automatically healthy; one range at 100% RU with a rate above 5% means redesign the key.