Analyze Cosmos DB partition key choices for cardinality and distribution.
Last verified: May 2026
Analyze Cosmos DB partition key choices for cardinality and distribution.
Required Fields
containercandidateKeyscandidateKeys[0]estimatedCardinalityestimatedCardinality./customerIdOutput will appear here...Your team is migrating from MongoDB to Cosmos DB for an SaaS app with 500 enterprise tenants, where the largest tenant has 30% of the data. The initial proposal: tenantId as partition key. The advisor flags hot partition risk: the top tenant alone would create a 6 TB logical partition (way over 20 GB limit). It recommends hierarchical partition keys [tenantId, userId] which keeps queries fast for the common 'this tenant's data' pattern while distributing the largest tenant across thousands of logical partitions.
The Cosmos DB Partition Key Advisor provides guidance on selecting the optimal partition key for your Azure Cosmos DB containers. The partition key is the most important design decision in Cosmos DB, affecting data distribution, query performance, and cost. This tool analyzes your access patterns, data model, and workload characteristics to recommend partition key candidates, estimate partition sizes, and warn about common anti-patterns like hot partitions.
The advisor takes inputs (data model fields with cardinality estimates, top 5 query patterns with expected frequency, write-vs-read ratio) and ranks partition key candidates by: (1) cardinality score (high cardinality = better distribution), (2) query alignment score (does it match top queries?), (3) hot partition risk (max single-value frequency). It also surfaces synthetic and hierarchical key alternatives when no single property scores well.
Hierarchical partition keys (added in 2023) let you specify up to 3 levels of partition keys, enabling efficient queries on the leading prefix while still distributing within the deepest level. For tenant_id + user_id + date scenarios, this is dramatically better than a synthetic concatenated key.
The 20 GB logical partition limit is a hard constraint, not a soft warning. If your partition key value (e.g., a power tenant) accumulates >20 GB of data, all writes fail with 413. Plan partition key cardinality assuming the largest single value will hit ~10 GB so you have headroom — and consider hierarchical keys for multi-tenant scenarios.
For write-heavy workloads, optimize for distribution; for read-heavy with point reads, optimize for query alignment. The wrong default is using userId for write-heavy multi-tenant analytics — power users create hot partitions. The right default is timestamp + userId hierarchical for analytics, or pure userId for OLTP.
Was this tool helpful?
Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.