表格存储 Java SDK 更新单行数据 - 表格存储

前提条件

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

功能说明

调用 updateRow 按完整主键更新一行数据，可新增或修改属性列、删除属性列的指定版本或全部版本，以及执行原子计数。

public UpdateRowResponse updateRow(UpdateRowRequest updateRowRequest) throws TableStoreException, ClientException

以下示例修改数据表 update_row_demo 中主键值为 row1 的行，将属性列 col1 的值改为 changed_val1。

String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
rowUpdateChange.put("col1", ColumnValue.fromString("changed_val1"));

client.updateRow(new UpdateRowRequest(rowUpdateChange));

参数说明

UpdateRowRequest 包含以下参数。

名称

类型

说明

rowChange（必选）

RowUpdateChange

单行更新配置。

transactionId（可选）

String

局部事务 ID。仅在局部事务内更新数据时设置。

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

行变更

rowChange 的类型为 RowUpdateChange，包含以下参数。

名称	类型	说明
tableName（必选）	`String`	数据表名称。
primaryKey（必选）	`PrimaryKey`	行主键。必须包含数据表的全部主键列，且列名称、顺序和类型必须与数据表的主键结构一致。主键列支持 `STRING`、`INTEGER` 和 `BINARY` 类型。
columnsToUpdate（必选）	`List<Pair<Column, RowUpdateChange.Type>>`	属性列变更列表。通过 `put`、`deleteColumn`、`deleteColumns` 或 `increment` 添加变更。
condition（可选）	`Condition`	更新条件，默认不检查行是否存在。关于条件的配置方法，请参见条件更新。
returnType（可选）	`ReturnType`	返回类型。默认值为 `RT_NONE`；原子计数器场景可设置为 `RT_AFTER_MODIFY`，返回更新后的列值。关于原子计数器的配置方法，请参见原子计数器。
returnColumnNames（可选）	`Set<String>`	要返回更新后值的属性列名称。仅用于原子计数器场景。

属性列变更方法

通过以下方法向 columnsToUpdate 添加属性列变更。

put：新增属性列或写入属性列的新版本，可指定数据版本号。
deleteColumn：删除属性列的指定版本。
deleteColumns：删除属性列的全部版本。
increment：对 INTEGER 类型属性列执行原子加操作。

返回值

UpdateRowResponse 包含以下业务字段。

字段	类型	说明
`row`	`Row`	更新后的属性列，通过 `getRow` 获取。仅当 `returnType` 设置为 `RT_AFTER_MODIFY` 时返回。

场景示例

写入指定版本号的属性列

通过 put 的第三个参数指定属性列的数据版本号（毫秒时间戳），适用于按业务时间归档历史值的场景。

String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
// 第三个参数指定数据版本号（毫秒时间戳）
long version = System.currentTimeMillis();
rowUpdateChange.put("col2", ColumnValue.fromString("val2"), version);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

删除属性列指定版本

通过 deleteColumn 删除指定版本号的列数据，其他版本保留。

String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
// 删除 col2 列指定版本号（毫秒时间戳）的数据
rowUpdateChange.deleteColumn("col2", 1747893563831L);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

删除整个属性列

通过 deleteColumns 删除属性列的所有版本数据。

String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
// 删除整个 col2 属性列（所有版本）
rowUpdateChange.deleteColumns("col2");

client.updateRow(new UpdateRowRequest(rowUpdateChange));