Azure Cosmos DB: Partition Keys and Data Modeling

Choosing the right partition key is the most important Cosmos DB decision you’ll make. Get it wrong, and you’ll hit performance issues. Here’s how to think about it.

What is a Partition Key?

Cosmos DB distributes data across physical partitions based on your partition key. All items with the same partition key value live together.

Good Partition Key Characteristics

• High cardinality: Many distinct values
• Even distribution: No hot spots
• Query alignment: Common queries filter on partition key

Examples

Good: /userId for user-centric data
Good: /tenantId for multi-tenant apps
Bad: /country for US-heavy traffic
Bad: /status (only 3-4 values = hot partitions)

Cross-Partition Queries

Queries that don’t filter on partition key cost more (fan-out to all partitions). Design your model to minimize these.

References

• Partitioning in Cosmos DB