CosmosDB Partition Internals: Logical vs Physical Partitions Explained

Scenario context

CosmosDB is a globally distributed, multi-model database designed to scale horizontally without the operational burden of manual sharding. To do this, it splits data across nodes — but it exposes two conceptually distinct partition layers rather than one.

The logical partition is your contract with the database: you declare a partition key, and CosmosDB groups every document with the same key value together. Th…

This walkthrough focuses on CosmosDB Partitioning: Why Two Layers Exist.

Before making a design choice, clarify:

• CosmosDB is a globally distributed, multi-model database designed to scale horizontally without the operational burden of manual sharding.
• To do this, it splits data across nodes — but it exposes two conceptually distinct partition layers rather than one.
• The logical partition is your contract with the database: you declare a partition key, and CosmosDB groups every document with the same key value together.

Concepts in play: database-sharding, database-indexing, caching, consistency-replication

Stage 1 — When Your Database Bill Triples Overnight

• A retail engineering team ships a flash-sale feature.
• Their Azure CosmosDB bill triples within 24 hours.
• Queries that ran in 5ms now take 800ms.
• The on-call engineer bumps provisioned RU/s from 10,000 to 40,000 — and the throttling barely improves.

Observable outcome: The on-call engineer bumps provisioned RU/s from 10,000 to 40,000 — and the throttling barely improves.

Stage 2 — Two Layers of Partitioning — One You Control, One You Don't

• CosmosDB partitions data across nodes to achieve horizontal scalability.
• It does this with two distinct abstractions that operate at different layers: Think of logical partitions as the filing system you design — you label every folder (partition key value).
• Physical partitions are the filing cabinets CosmosDB builds — it decides which folders go in which cabinet, and it can add cabinets automatically as you fill them.
• A logical partition is the set of all documents that share the same partition key value.

Observable outcome: A logical partition is the set of all documents that share the same partition key value.

Stage 3 — How CosmosDB Routes Requests: The Hash-Range Mapping

• The routing layer between your application and physical storage is a partition key hash space spanning from 0x0000 to 0xFFFF .
• CosmosDB hashes each document's partition key value into this range.
• Physical partitions own contiguous slices of the hash space, and logical partitions land in the physical partition that owns their hash.
• This diagram shows how a client request reaches a physical partition.

graph TD
    A[Client Request] --> B[CosmosDB Gateway]
    B --> C[Partition Key Router]
    C --> D{Hash of Partition Key}
    D --> E[Physical Partition 1 - Range 0x0000 to 0x3FFF]
    D --> F[Physical Partition 2 - Range 0x4000 to 0x7FFF]
    D --> G[Physical Partition 3 - Range 0x8000 to 0xBFFF]
    D --> H[Physical Partition 4 - Range 0xC000 to 0xFFFF]
    E --> I[LP: userId-A, userId-B, userId-C]
    F --> J[LP: userId-D, userId-E]
    G --> K[LP: userId-F, userId-G, userId-H]
    H --> L[LP: userId-J, userId-K]

Observable outcome: This diagram shows how a client request reaches a physical partition.

Stage 4 — Partition Splitting Internals: How CosmosDB Scales Without Downtime

• The Internals of a Split CosmosDB triggers a physical partition split under two conditions: 1.
• Data volume: The physical partition approaches ~50 GB.
• Throughput scale-up: You increase provisioned or autoscale RU/s and CosmosDB needs to spread load across more partitions to fulfill the new capacity.
• When a split occurs, CosmosDB divides the hash range of the original physical partition into two equal halves and migrates each half's logical partitions to one of the two resulting physical partitions.

graph TD
    A[Physical Partition P1 - 45GB - 8000 RU/s] -->|Split triggered| B[Physical Partition P1a - 22GB - 4000 RU/s]
    A -->|Split triggered| C[Physical Partition P1b - 23GB - 4000 RU/s]
    B --> D[Logical Partitions LP1 to LP5]
    C --> E[Logical Partitions LP6 to LP10]

Observable outcome: When a split occurs, CosmosDB divides the hash range of the original physical partition into two equal halves and migrates each half's logical partitions to one of the two resulting physical partitions.

Stage 5 — Hot Partition Flow: How a Bad Key Saturates Physical Storage

• Physical partition splits and increased RU/s cannot save you from a poorly chosen partition key.
• The fundamental problem is at the logical partition layer — before CosmosDB's elasticity mechanisms even get involved.
• Scenario 1: Low-Cardinality Key Three logical partitions exist regardless of how many millions of orders you store.
• Ninety percent of queries target status = "active" .

container: "orders"
partitionKey: "/status"
values: ["active", "completed", "cancelled"]

Observable outcome: Ninety percent of queries target status = "active" .

Stage 6 — Practical: Choosing and Fixing Partition Keys

• The goal is high cardinality + uniform access distribution + query alignment .
• Synthetic Partition Keys for Difficult Workloads When your data does not have a natural high-cardinality key, build one: Suffix bucketing — append a modulo bucket to an existing key: orderId + " " + (epochSeconds % 50)…
• Distributing writes across sensorId 0 through sensorId 99 prevents 100% of write traffic from hitting a single logical partition.

Observable outcome: Distributing writes across sensorId 0 through sensorId 99 prevents 100% of write traffic from hitting a single logical partition.

End-to-end outcome

CosmosDB is a globally distributed, multi-model database designed to scale horizontally without the operational burden of manual sharding.

Alternatives considered

Decision Guide: Selecting a Partition Key by Use Case

Decision Guide: Selecting a Partition Key by Use Case

Failure and degraded modes

Scenario | Root Cause | Observable Impact | Resolution |

• Detection: Scenario | Root Cause | Observable Impact | Resolution |
• User or operator impact: Scenario | Root Cause | Observable Impact | Resolution |

The Cross-Partition Query Tax

• Detection: A query without a partition key filter executes as a fan-out — CosmosDB sends the query to every physical partition in parallel and merges results.
• User or operator impact: A query without a partition key filter executes as a fan-out — CosmosDB sends the query to every physical partition in parallel and merges results.

Lessons Learned from CosmosDB Partition Failures

• Detection: - The 20 GB limit is a hard wall with no operational escape hatch.
• User or operator impact: - The 20 GB limit is a hard wall with no operational escape hatch.