为何在Azure Cosmos DB容器中创建项时需单独传入分区键值？

当我们在Azure Cosmos DB for NoSQL中创建容器时，已经通过partitionKeyPath指定了分区键对应的属性，但添加项时仍需单独传入分区键值，主要有以下几个原因：

• 消除属性解析的不确定性：如果文档结构复杂（比如嵌套多层的属性），或者属性名存在大小写差异（Cosmos DB对属性名大小写敏感），让Cosmos DB自动解析文档提取分区键可能出现错误。单独传入分区键值可以直接明确指定分区，避免解析过程中的歧义。

• 优化操作性能：提前传入分区键值后，Cosmos DB可以直接定位到目标分区，不需要先读取并解析整个文档来提取分区键，减少了文档解析的开销，让写入、查询等操作的响应速度更快。

• 支持灵活的业务场景：有些场景下你可能需要使用和文档属性值不同的分区键（比如临时用其他值做分区测试，或者对属性值做哈希、转换后再作为分区键），单独传入分区键值可以实现这种需求，不需要修改文档本身的属性内容。

• 保持API使用逻辑的一致性：在执行更新、删除等操作时，你可能只有项的ID和分区键，没有完整的文档内容，此时必须传入分区键才能定位到对应的分区。让CreateItemAsync也要求传入分区键，能让整个SDK的使用逻辑保持统一，避免开发者在不同操作中混淆参数要求。

创建容器的.NET SDK示例 #

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "food",
    partitionKeyPath: "/food_group",
    throughput: 400
);

添加项的.NET SDK示例 #

Food item = new (
    id: "53634634",
    food_group: "fruit",
    name: "Apple"
);

Food createdItem = await container.CreateItemAsync<Food>(
    item: item,
    partitionKey: new PartitionKey("fruit")
);

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