表格存储 Java SDK 原子计数器-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

安装 Tablestore Java SDK并初始化客户端。

功能说明

调用 increment(Column) 对指定整型列执行原子计数：正数表示递增，负数表示递减。服务端在行级别保证操作的原子性，并在更新完成后写入一个新的数据版本。如需在同一请求中获取更新后的值，调用 addReturnColumn(String) 指定返回列，并将 returnType 设置为 RT_AFTER_MODIFY。

public UpdateRowResponse updateRow(UpdateRowRequest updateRowRequest) throws TableStoreException, ClientException
public RowUpdateChange increment(Column column)
public void addReturnColumn(String columnName)
public void setReturnType(ReturnType returnType)

以下示例对数据表 counter_demo 中主键 pk0 的行执行 price 列递增 10 操作，并在同一请求中读取更新后的值。

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("pk0"))
        .build();

RowUpdateChange rowUpdateChange = new RowUpdateChange("counter_demo", primaryKey);

// 对 price 列执行递增操作，加 10（负数表示递减）
rowUpdateChange.increment(new Column("price", ColumnValue.fromLong(10)));

// 同一请求中返回更新后的列值
rowUpdateChange.addReturnColumn("price");
rowUpdateChange.setReturnType(ReturnType.RT_AFTER_MODIFY);

UpdateRowResponse response = client.updateRow(new UpdateRowRequest(rowUpdateChange));
Row row = response.getRow();
System.out.println("Updated price: " + row.getLatestColumn("price").getValue().asLong());

参数说明

请求配置

UpdateRowRequest 包含以下参数。

名称

类型

说明

rowChange（必选）

RowUpdateChange

单行更新配置。

transactionId（可选）

String

局部事务 ID。仅在局部事务内执行原子计数时设置。

关于如何获取和使用该 ID，请参见局部事务。

行更新配置

UpdateRowRequest.rowChange 的类型为 RowUpdateChange。

名称	类型	说明
tableName（必选）	String	数据表名称。
primaryKey（必选）	PrimaryKey	目标行的主键。
columnsToUpdate（必选）	List<Pair<Column, Type>>	要更新的属性列。调用 `increment(Column)` 添加原子计数操作。
condition（可选）	Condition	条件更新配置。仅当目标行满足条件时执行原子计数。关于条件的配置方法，请参见条件更新。
returnType（可选）	ReturnType	返回类型。默认值为 `RT_NONE`；如需返回更新后的值，设置为 `RT_AFTER_MODIFY`。
returnColumnNames（可选）	Set<String>	要返回更新后值的原子计数列名称。通过 `addReturnColumn()` 添加，并与 `RT_AFTER_MODIFY` 配合使用。

计数列

通过 increment() 添加到 UpdateRowRequest.rowChange.columnsToUpdate 的每个元素都包含一个 Column 对象。

名称	类型	说明
name（必选）	String	执行原子计数的属性列名称。
value（必选）	ColumnValue	整型增量。正数表示递增，负数表示递减；计算结果不能溢出。目标列不存在时，以 0 为初始值执行计算。

返回值

名称	类型	说明
row	Row	设置 `RT_AFTER_MODIFY` 后，包含通过 `addReturnColumn()` 指定的原子计数列更新后值。通过 `getRow()` 获取。

使用限制

目标列已存在但非整型时，返回 OTSParameterInvalid 错误。
原子计数操作只作用于最新版本，不支持指定时间戳。
单次更新请求中，对同一列不能同时执行原子计数和其他操作（如覆盖写、删除等）。
BatchWriteRow 请求中，已执行原子计数的行只能在批次中出现一次。

重要

原子计数操作可能因网络超时、系统错误等失败，重试时可能更新两次原子计数器，导致计数偏多或偏少。此类异常场景建议使用条件更新精确变更列值。