Azure Cosmos DB Upsert功能异常：为何更新数据时报重复键错误？

问题原因 #

Cosmos DB的upsert()方法判断"插入"还是"更新"的核心依据是分区键 + 文档ID，和你设置的唯一键sku没有关联。第一次插入时你未指定id字段，Cosmos会自动生成一个唯一ID；第二次执行upsert时，你同样没携带id，Cosmos会尝试生成新ID插入，但此时sku是唯一键，重复的sku触发了唯一键约束，因此报错。

解决方法 #

不需要拆分创建或更新两步，两种方案可解决问题：

1. Upsert时携带文档ID #

第一次插入成功后，Cosmos会返回包含id字段的完整文档，将这个id保存下来。第二次更新时，把id加入到要upsert的对象中：

// 假设第一次插入后得到的id是"abc123"
const product = { 
  id: "abc123",
  sku: 1, 
  name: "UpdatedAwesomeProduct", 
  category_id: 100 
};
await container.items.upsert(product);

此时Cosmos会通过category_id（分区键）+id定位到原文档，执行更新操作，不会触发唯一键冲突。

2. 先通过唯一键查询文档再更新 #

如果无法保存第一次的id，可以通过SQL查询结合sku和分区键找到目标文档，拿到id后再执行upsert或replace：

// 构建查询，指定分区键提升查询性能
const querySpec = {
  query: "SELECT * FROM c WHERE c.sku = @sku AND c.category_id = @categoryId",
  parameters: [
    { name: "@sku", value: 1 },
    { name: "@categoryId", value: 100 }
  ]
};
const { resources: products } = await container.items.query(querySpec).fetchAll();

if (products.length > 0) {
  const existingProduct = products[0];
  existingProduct.name = "UpdatedAwesomeProduct";
  // 用upsert或replace均可
  await container.items.upsert(existingProduct);
  // 或者使用replace更明确：await container.item(existingProduct.id, existingProduct.category_id).replace(existingProduct);
}

补充说明 #

唯一键sku的作用是阻止插入重复sku的文档，但不会影响Upsert的匹配逻辑。只要让Upsert能通过分区键+ID定位到已存在的文档，就能正常执行更新操作。

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