Partition Key Strategy | Guided by A Guide to Cloud

Why the partition key is everything

Simple explanation

Imagine a library with millions of books. The partition key is how you organise the shelves. If you sort by “first letter of the author’s last name,” shelf “S” gets Shakespeare, Spielberg, and 10,000 other authors — it overflows. But if you sort by a full author ID, each shelf has a manageable number of books.

A bad partition key creates one overloaded shelf (a hot partition). A good key spreads books evenly so every shelf does its fair share of work.

Physical vs logical partitions

Concept	Logical partition	Physical partition
Definition	All items sharing the same partition key value	A physical storage unit managed by Cosmos DB
Size limit	20 GB per logical partition	~50 GB per physical partition
Throughput limit	N/A (shares the physical partition’s RU budget)	10,000 RU/s per physical partition
Who manages it	You (via partition key choice)	Cosmos DB (automatic splits)
Contains	Items with identical PK value	One or more logical partitions

Physical partition 1 (50 GB max, 10K RU/s)
  ├── Logical partition: tenantId = "abc"  (15 GB)
  └── Logical partition: tenantId = "def"  (8 GB)

Physical partition 2 (50 GB max, 10K RU/s)
  ├── Logical partition: tenantId = "ghi"  (12 GB)
  └── Logical partition: tenantId = "jkl"  (3 GB)

Key insight: Cosmos DB automatically splits physical partitions as data grows. But a single logical partition can never be split — all items with the same PK value must stay together on one physical partition.

The three rules of a good partition key

Rule 1: High cardinality

The key should have many distinct values — ideally as many as there are items, or close to it.

❌ /country       → ~200 values for millions of documents
❌ /status        → 3-5 values (active, inactive, archived)
✅ /tenantId      → thousands of distinct tenants
✅ /userId        → one per user
✅ /orderId       → one per order (highest cardinality)

Rule 2: Even distribution

Traffic and storage should spread evenly across partition key values. No single value should dominate.

❌ /companyId in a B2B app where one company has 80% of data
   → That one logical partition becomes a hot partition

✅ /userId in a consumer app with millions of balanced users
   → Each user's data is roughly the same size

Rule 3: Query alignment

Your most frequent queries should include the partition key in the WHERE clause.

-- ✅ Single-partition query (fast, ~1 RU for point read)
SELECT * FROM c WHERE c.tenantId = 'abc' AND c.type = 'task'

-- ❌ Cross-partition query (fan-out, 10× more RU)
SELECT * FROM c WHERE c.type = 'task' AND c.status = 'overdue'

Priya’s scenario: choosing the right key

🚀 Priya evaluates partition key candidates for her workitems container:

Candidate	Cardinality	Distribution	Query alignment	Verdict
`/tenantId`	Medium (1,000 tenants)	⚠️ One enterprise tenant has 60% of data	✅ Every query filters by tenant	Risky — hot partition
`/projectId`	High (50,000 projects)	✅ Projects are roughly equal size	⚠️ Task queries need projectId + tenantId	Possible
`/id`	Perfect (unique per item)	✅ Perfectly even	❌ Queries never filter by id alone	Too scattered
`/tenantId + type`	Higher (1,000 × 5 types)	✅ Better spread	✅ Most queries filter by both	Better — but synthetic key needed

Priya decides on /tenantId for now but plans to evaluate hierarchical partition keys (next module) once she confirms the enterprise tenant’s data exceeds 20 GB.

Read-heavy vs write-heavy strategies

Strategy	Read-heavy workloads	Write-heavy workloads
Goal	Minimise cross-partition reads	Distribute writes across many partitions
Ideal PK	Matches your WHERE clause filters	High cardinality (e.g., /deviceId, /eventId)
Example	/tenantId for 'get all tasks for tenant X'	/deviceId for IoT sensor writes
Trade-off	May concentrate writes on popular tenants	Reads that span devices need fan-out
Common pattern	Denormalise + type discriminator	Append-only with synthetic/random suffix
Risk	Hot partition on popular key values	Cross-partition queries for aggregations

Common partition key mistakes

Mistake	Why it’s bad	Fix
Using `/date` or `/timestamp`	All today’s writes go to one partition (hot write)	Use `/deviceId` or append a random suffix
Using a low-cardinality field like `/status`	3-5 partitions total — can’t scale	Use the entity’s natural ID
Choosing a key that doesn’t appear in queries	Every query becomes cross-partition	Align the key with your WHERE clauses
Ignoring the 20 GB logical limit	One large tenant fills the partition	Use hierarchical keys or synthetic keys
Assuming you can change it later	The partition key is immutable after container creation	Design carefully upfront; migration = new container + data copy

Ravi’s mistake: Ravi chose /createdDate (a date string like “2025-06-15”) as the partition key for the audit log container. On a busy day, all writes hammer the same partition. He got 429 (throttled) errors even though the container had plenty of total RU/s — because one physical partition was maxed at 10,000 RU/s.

Exam tip: partition key is immutable

You cannot change the partition key after creating a container. If you chose wrong, the only fix is to create a new container with the correct key and migrate data. The exam tests this — know that there’s no ALTER CONTAINER SET PARTITION KEY equivalent. Plan carefully or use the emulator to prototype first.

Exam tip: 429 on a single partition

You can get 429 (Too Many Requests) even when total RU/s isn’t exhausted — if a single physical partition exceeds its ~10,000 RU/s allocation. This is the classic hot partition symptom. The fix is a better partition key with more even distribution, not more total RU/s.

🎬 Video walkthrough

🎬 Video coming soon

Partition Key Strategy — DP-420 Module 3

~18 min