如何使用Java SDK实现Cosmos DB SQL API的部分更新操作

前置依赖 #

• 必须使用 4.19.0 及以上版本的 azure-cosmos Java SDK，低于该版本无原生部分更新（Patch）能力
• 已提前创建好 Cosmos DB 账号、数据库、容器，且拿到了账号的访问密钥和端点地址

Maven 依赖参考：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.42.0</version> <!-- 建议使用官方最新稳定版 -->
</dependency>

操作步骤 #

1. 初始化客户端和容器实例 #

建议客户端在项目中单例复用，避免重复创建产生性能损耗：

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint("你的Cosmos DB服务端点")
    .key("你的Cosmos DB访问密钥")
    .consistencyLevel(ConsistencyLevel.EVENTUAL)
    .buildClient();

CosmosDatabase db = cosmosClient.getDatabase("目标数据库名称");
CosmosContainer container = db.getContainer("目标容器名称");

2. 构造 Patch 操作列表 #

单次部分更新最多支持10个操作，支持的操作类型包括字段新增/修改、字段删除、数值增减、数组元素修改等：

List<CosmosPatchOperation> patchOps = new ArrayList<>();
// 新增/更新字段：存在则覆盖，不存在则新增
patchOps.add(CosmosPatchOperation.set("/orderStatus", "已发货"));
patchOps.add(CosmosPatchOperation.set("/deliveryInfo.expressCode", "SF123456789"));
// 删除指定字段
patchOps.add(CosmosPatchOperation.remove("/unusedField"));
// 数值增量修改：给当前的totalAmount字段加20.5
patchOps.add(CosmosPatchOperation.increment("/totalAmount", 20.5));
// 数组追加元素：给goodsList数组末尾添加新元素
patchOps.add(CosmosPatchOperation.add("/goodsList/-", "{\"id\":\"g005\",\"name\":\"赠品\"}"));

路径规则说明：所有路径以/开头，嵌套层级用/拼接；数组末尾追加元素的固定写法为/数组字段名/-

3. 执行部分更新请求 #

传入待更新文档的id、分区键值和操作列表即可执行：

// 可按需配置请求参数，比如一致性级别、超时时间等
CosmosPatchRequestOptions patchOptions = new CosmosPatchRequestOptions();
patchOptions.setConsistencyLevel(ConsistencyLevel.SESSION);

// 执行Patch操作，最后一个参数为返回结果的反序列化类型
CosmosItemResponse<Map> resp = container.patchItem(
    "待更新文档的id",
    new PartitionKey("待更新文档的分区键值"),
    patchOps,
    patchOptions,
    Map.class
);

// 操作结果校验
if (resp.getStatusCode() == 200) {
    System.out.println("更新成功，更新后文档内容：" + resp.getItem());
}

实际踩坑注意点 #

• 所有操作是原子性的，只要有一个操作执行失败，整个更新请求会回滚
• 如果待更新的文档不存在，会直接返回404，不会自动创建文档
• 单次请求的操作列表不能超过10个，超出会直接返回参数错误
• 如果要更新的嵌套字段的上级节点不存在，会自动创建上级节点

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