表格存储 Java SDK 写入单行数据 - 表格存储

前提条件

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

功能说明

调用 putRow 向指定主键的行写入属性列。如果行已存在，将新增或覆盖相应属性列的数据版本；可通过 condition 控制写入是否执行。

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

以下示例向数据表 put_row_demo 写入主键值为 row1 的一行数据，属性列 col1 取值 val1。

String tableName = "put_row_demo";

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

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"));

client.putRow(new PutRowRequest(rowPutChange));

参数说明

PutRowRequest 包含以下参数。

名称	类型	说明
rowChange（必选）	`RowPutChange`	单行写入配置。
transactionId（可选）	`String`	局部事务 ID。仅在局部事务内写入数据时设置。

行变更

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

名称	类型	说明
tableName（必选）	`String`	数据表名称。
primaryKey（必选）	`PrimaryKey`	行主键。主键列的名称、顺序和类型必须与数据表的主键结构一致。主键列支持 `STRING`、`INTEGER` 和 `BINARY` 类型。自增主键列的值必须设置为 `PrimaryKeyValue.AUTO_INCREMENT`。
columnsToPut（可选）	`List<Column>`	要写入的属性列列表。可多次调用 `addColumn` 逐列添加，也可调用 `addColumns` 批量添加。
condition（可选）	`Condition`	写入条件，默认不检查行是否存在。
returnType（可选）	`ReturnType`	返回类型。默认值为 `RT_NONE`，不返回主键信息；设置为 `RT_PK` 时返回完整主键，常用于获取自增主键值。

属性列

rowChange.columnsToPut[] 的类型为 Column，包含以下参数。

名称	类型	说明
name（必选）	`String`	属性列名称。
value（必选）	`ColumnValue`	属性列值。支持 `STRING`、`INTEGER`、`BINARY`、`DOUBLE` 和 `BOOLEAN` 类型。
timestamp（可选）	`long`	数据版本号，单位为毫秒。未设置时由服务端自动生成。

场景示例

写入多个属性列

通过多次调用 addColumn 逐列添加，或一次性传入 List<Column> 构造。

String tableName = "put_row_demo";

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

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);

// 方式一：多次调用 addColumn 逐列添加
rowPutChange.addColumn("name", ColumnValue.fromString("Alice"));
rowPutChange.addColumn("age", ColumnValue.fromLong(30));
rowPutChange.addColumn("active", ColumnValue.fromBoolean(true));

// 方式二：一次性传入 List<Column> 构造
List<Column> columns = new ArrayList<>();
columns.add(new Column("score", ColumnValue.fromDouble(95.5)));
columns.add(new Column("city", ColumnValue.fromString("Hangzhou")));
rowPutChange.addColumns(columns);

client.putRow(new PutRowRequest(rowPutChange));

指定数据版本号

使用 addColumn(name, value, timestamp) 在写入时指定数据版本号。

String tableName = "put_row_demo";

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

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);

long timestamp = System.currentTimeMillis();
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"), timestamp);

client.putRow(new PutRowRequest(rowPutChange));

自增列写入返回主键

自增列的主键值使用占位符 PrimaryKeyValue.AUTO_INCREMENT，由服务端生成真实值。设置 setReturnType(ReturnType.RT_PK) 后，可通过 response.getRow() 读出真实主键。

String tableName = "put_row_auto_inc_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("partition_key", PrimaryKeyValue.fromString("pk1"));
primaryKeyBuilder.addPrimaryKeyColumn("auto_id", PrimaryKeyValue.AUTO_INCREMENT);
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("payload", ColumnValue.fromString("hello"));
rowPutChange.setReturnType(ReturnType.RT_PK);

PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
Row returnedRow = response.getRow();
System.out.println("Returned PK: " + returnedRow.getPrimaryKey());