From 5e8a0a6b2d6e03e4f11c1c7a9c4d6b086ec98de1 Mon Sep 17 00:00:00 2001 From: Bhuvansh855 Date: Fri, 19 Jun 2026 21:55:07 +0530 Subject: [PATCH 1/4] feat(partition): add query-pattern tie-breaker guidance --- .../rules/partition-high-cardinality.md | 10 ++++++++++ .../rules/partition-query-patterns.md | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md b/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md index e32d487d..3fe201bc 100644 --- a/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md +++ b/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md @@ -77,4 +77,14 @@ Good partition keys typically: - Match your most common query patterns - Distribute writes evenly (no single key dominates) +### Cardinality vs. Query Patterns + +High cardinality is important for even distribution, but it should not be the sole factor when selecting a partition key. + +For read-heavy workloads where most queries filter on a specific field, prefer a partition key aligned with the dominant query pattern even if its cardinality is lower than `/id`. Single-partition reads are often more efficient than maximizing distribution that the workload does not require. + +A bare `/id` partition key is most appropriate when point reads by id are the dominant access pattern or when write throughput requires maximum distribution. If the dominant query pattern filters on another field, consider whether aligning the partition key with that field would reduce cross-partition queries. + +See also: `partition-query-patterns`. + Reference: [Partitioning in Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db/partitioning-overview) diff --git a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md index 9563c155..104d8962 100644 --- a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md +++ b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md @@ -83,4 +83,14 @@ public class Message // "Get messages in conversation" - single partition, fast ``` +### Query Alignment vs. Cardinality + +When query-pattern guidance conflicts with pure cardinality guidance, favor the partition key that supports the dominant access pattern for read-heavy workloads. + +For example, if most queries filter by `Category`, partitioning by `Category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition and avoids unnecessary cross-partition scans. + +If the query field has insufficient cardinality and may create hot partitions, consider a synthetic or hierarchical partition key that preserves query alignment while improving distribution. + +See also: `partition-high-cardinality`. + Reference: [Choose a partition key](https://learn.microsoft.com/azure/cosmos-db/partitioning-overview#choose-a-partition-key) From 040d75a9c42295a11f57495c002da867bbe0647f Mon Sep 17 00:00:00 2001 From: Bhuvansh855 Date: Fri, 19 Jun 2026 22:00:13 +0530 Subject: [PATCH 2/4] refine partition key tie-breaker guidance --- .../rules/partition-high-cardinality.md | 4 ++-- .../cosmosdb-best-practices/rules/partition-query-patterns.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md b/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md index 3fe201bc..006cbb0d 100644 --- a/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md +++ b/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md @@ -81,9 +81,9 @@ Good partition keys typically: High cardinality is important for even distribution, but it should not be the sole factor when selecting a partition key. -For read-heavy workloads where most queries filter on a specific field, prefer a partition key aligned with the dominant query pattern even if its cardinality is lower than `/id`. Single-partition reads are often more efficient than maximizing distribution that the workload does not require. +For read-heavy workloads that can grow to multiple physical partitions and where most queries use an equality filter on a specific field, prefer a partition key aligned with that dominant query pattern even if its cardinality is lower than `/id`. Single-partition reads are often more efficient than cross-partition fan-out for the dominant access pattern. -A bare `/id` partition key is most appropriate when point reads by id are the dominant access pattern or when write throughput requires maximum distribution. If the dominant query pattern filters on another field, consider whether aligning the partition key with that field would reduce cross-partition queries. +A bare `/id` partition key is most appropriate when point reads by `/id` are the dominant access pattern, when the container is small enough that cross-partition fan-out is not a concern, or when write throughput requires maximum distribution. If the dominant query pattern filters on another field, consider whether aligning the partition key with that field would reduce cross-partition queries. See also: `partition-query-patterns`. diff --git a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md index 104d8962..14911180 100644 --- a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md +++ b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md @@ -85,9 +85,9 @@ public class Message ### Query Alignment vs. Cardinality -When query-pattern guidance conflicts with pure cardinality guidance, favor the partition key that supports the dominant access pattern for read-heavy workloads. +When query-pattern guidance conflicts with pure cardinality guidance, favor the partition key that supports the dominant access pattern, especially for read-heavy workloads that can grow to multiple physical partitions. -For example, if most queries filter by `Category`, partitioning by `Category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition and avoids unnecessary cross-partition scans. +For example, if most queries use an equality filter by `Category`, partitioning by `Category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition (when you supply the `PartitionKey` value) and avoids unnecessary cross-partition fan-out. If the query field has insufficient cardinality and may create hot partitions, consider a synthetic or hierarchical partition key that preserves query alignment while improving distribution. From 13129aee47fe425fb87395e301a3a55a77eb6acd Mon Sep 17 00:00:00 2001 From: Bhuvansh855 Date: Fri, 19 Jun 2026 22:05:27 +0530 Subject: [PATCH 3/4] clarify partition key cardinality guidance --- .../rules/partition-high-cardinality.md | 4 ++-- .../cosmosdb-best-practices/rules/partition-query-patterns.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md b/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md index 006cbb0d..158dd41c 100644 --- a/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md +++ b/skills/cosmosdb-best-practices/rules/partition-high-cardinality.md @@ -81,9 +81,9 @@ Good partition keys typically: High cardinality is important for even distribution, but it should not be the sole factor when selecting a partition key. -For read-heavy workloads that can grow to multiple physical partitions and where most queries use an equality filter on a specific field, prefer a partition key aligned with that dominant query pattern even if its cardinality is lower than `/id`. Single-partition reads are often more efficient than cross-partition fan-out for the dominant access pattern. +For read-heavy workloads that can grow to multiple physical partitions and where most queries use an equality filter on a specific field, prefer a partition key aligned with that dominant query pattern even if its cardinality is lower than `/id`, as long as it still provides sufficient cardinality to avoid hot partitions. If the query-aligned field is too low-cardinality, consider a synthetic or hierarchical partition key to preserve query alignment while improving distribution. -A bare `/id` partition key is most appropriate when point reads by `/id` are the dominant access pattern, when the container is small enough that cross-partition fan-out is not a concern, or when write throughput requires maximum distribution. If the dominant query pattern filters on another field, consider whether aligning the partition key with that field would reduce cross-partition queries. +A bare `/id` partition key is most appropriate when point reads by `/id` are the dominant access pattern, when the container is small enough to remain within a single physical partition, or when write throughput requires maximum distribution. If the dominant query pattern filters on another field, consider whether aligning the partition key with that field would reduce cross-partition queries. See also: `partition-query-patterns`. diff --git a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md index 14911180..244ec8f8 100644 --- a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md +++ b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md @@ -87,7 +87,7 @@ public class Message When query-pattern guidance conflicts with pure cardinality guidance, favor the partition key that supports the dominant access pattern, especially for read-heavy workloads that can grow to multiple physical partitions. -For example, if most queries use an equality filter by `Category`, partitioning by `Category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition (when you supply the `PartitionKey` value) and avoids unnecessary cross-partition fan-out. +For example, if most queries use an equality filter on `/category` (and `category` has sufficient cardinality to avoid hot partitions), partitioning by `/category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition (when you supply the `PartitionKey` value) and avoids unnecessary cross-partition fan-out. If the query field has insufficient cardinality and may create hot partitions, consider a synthetic or hierarchical partition key that preserves query alignment while improving distribution. From 5a4e3e98539e7960ae85237496e140aafa3d0a5d Mon Sep 17 00:00:00 2001 From: Bhuvansh855 Date: Fri, 19 Jun 2026 22:05:33 +0530 Subject: [PATCH 4/4] clarify partition key cardinality guidance --- .../cosmosdb-best-practices/rules/partition-query-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md index 244ec8f8..49ecf5e6 100644 --- a/skills/cosmosdb-best-practices/rules/partition-query-patterns.md +++ b/skills/cosmosdb-best-practices/rules/partition-query-patterns.md @@ -89,7 +89,7 @@ When query-pattern guidance conflicts with pure cardinality guidance, favor the For example, if most queries use an equality filter on `/category` (and `category` has sufficient cardinality to avoid hot partitions), partitioning by `/category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition (when you supply the `PartitionKey` value) and avoids unnecessary cross-partition fan-out. -If the query field has insufficient cardinality and may create hot partitions, consider a synthetic or hierarchical partition key that preserves query alignment while improving distribution. +If `/category` has insufficient cardinality and may create hot partitions, consider a synthetic or hierarchical partition key that preserves query alignment while improving distribution. See also: `partition-high-cardinality`.