Cosmos DB查询示例无需指定partitionKey的原因及性能疑问

问题说明 #

我发现微软Cosmos DB NoSQL的快速入门文档里，查询示例没有指定分区键（PartitionKey）。我理解全库查询的场景存在，但明明限定到特定分区查询效率更高，为什么示例要这么写？

文档中的代码示例（整理后）：

string queryText = "SELECT * FROM products p WHERE p.category = @category";

var queryDefinition = new QueryDefinition(queryText)
  .WithParameter("@category", "gear-surf-surfboards");

using FeedIterator<Product> feedIterator = container.GetItemQueryIterator<Product>(
    queryDefinition: queryDefinition
);

为什么示例不指定分区键？ #

• 简化教学，聚焦基础流程：快速入门的核心是让开发者最快掌握"构造参数化查询→执行查询→迭代结果"的基础流程。加入分区键参数会增加代码复杂度，分散新手的注意力，不符合入门教程的定位。
• 自动路由的隐性逻辑：如果查询里的过滤字段恰好是容器的分区键，Cosmos DB会自动识别并只查询对应分区，不需要显式指定。但如果category不是分区键，这段代码就会触发跨分区查询——示例没明确说明这一点，是为了避免引入过多进阶概念。
• 覆盖通用场景：示例要适配更多通用查询场景，而不是只针对分区键过滤的情况。显式指定分区键属于性能优化的进阶技巧，这类内容通常会放在专门的性能调优文档里，不会在入门示例中堆砌。

分区查询的最佳实践 #

• 明确分区时必指定：只要你知道目标数据所在的分区，一定要在查询时通过PartitionKey参数指定（比如给GetItemQueryIterator加上partitionKey: new PartitionKey("你的分区值")），这能彻底避免跨分区查询的额外开销，性能提升非常明显。
• 区分过滤字段类型：如果查询的过滤字段不是分区键，哪怕不指定分区键，也会触发跨分区查询。这种情况下要么接受性能损耗，要么考虑调整分区策略，或者给过滤字段添加复合索引来优化。

内容的提问来源于stack exchange，提问作者Sam