Azure Forums

Understanding Partition Keys

A partition key is a property in your document that Cosmos DB uses to distribute your data across multiple logical and physical partitions. Choosing the right partition key is paramount for a successful Cosmos DB deployment. A good partition key ensures:

• Even data distribution: Prevents hot partitions where one partition receives a disproportionate amount of traffic.
• Scalability: Allows Cosmos DB to scale out your throughput and storage seamlessly.
• Performance: Optimizes query latency by routing requests to the relevant partitions.

A bad partition key can lead to:

• Throttling (RU exhaustion): Requests targeting a hot partition might exceed its allocated Request Units (RUs).
• Poor query performance: Queries may need to scan multiple partitions.
• Increased costs: Inefficient RU usage can drive up costs.

Common Pitfalls and How to Avoid Them

One of the most common mistakes is choosing a partition key with low cardinality, like a boolean flag or a status that has only a few distinct values. This will inevitably lead to a hot partition.

Another pitfall is using a partition key that is frequently updated. While Cosmos DB supports updates, frequent updates on a partition key can be inefficient.

Example of a bad choice: Using tenantId if you have only a few tenants.

{
    "id": "doc123",
    "data": "some valuable info",
    "tenantId": "tenant-A"
}

Instead, consider:

• Synthetic Keys: If natural keys aren't ideal, consider creating a synthetic key by combining properties.
• Root-level Properties: Prefer partition keys that are at the root of your document.
• Immutable Keys: Choose properties that don't change often.

Advanced Strategies and Considerations

For large-scale applications, techniques like prefixing or salting partition keys can help distribute load more evenly if a natural key has some skew.

For example, if your partition key is userId and some users are extremely active, you might transform it:

// Original
userId: "user-123"

// Transformed (e.g., with a simple prefix based on user ID length)
partitionKey: "u-" + userId

Or, for very high-volume scenarios, consider sharding your partition key at the application level, creating a composite key or a logical partitioning scheme.

Request Unit (RU) Management: Remember that your partition key influences how RUs are consumed. Ensure your partition strategy aligns with your provisioned throughput.

Data Migration: If you need to change your partition key, be aware that this is a significant operation that typically involves creating a new container and migrating data. Plan carefully!

Revisiting Partition Key Choices

It's essential to understand that the partition key is immutable once the container is created. If you realize your initial choice was suboptimal, you cannot change it directly on the existing container.

The process to "change" a partition key involves:

1. Creating a new container with the desired partition key.
2. Migrating data from the old container to the new one.
3. Updating your application to point to the new container.
4. Deleting the old container.

This is why thorough planning is critical. Consider your long-term growth and potential use cases.

Some common recommended partition keys include:

• Tenant ID (if you have many tenants and queries are often scoped to a tenant)
• User ID (for user-centric applications, but be mindful of activity skew)
• Date/Time components (like YearMonthDay, but ensure high cardinality)
• Geographic Location (if relevant for data partitioning)

Final Recommendation: For most scenarios, choose a partition key with the highest cardinality that aligns with your most frequent and critical query patterns.