表格存储 Java SDK 批量数据操作-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

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

功能说明

调用 batchWriteRow 在单次请求中跨表混合执行写入、更新和删除行操作。服务端按行独立处理，单行失败不影响其他行；可通过 isAllSucceed 和 getFailedRows 判断执行结果。

public BatchWriteRowResponse batchWriteRow(BatchWriteRowRequest batchWriteRowRequest) throws TableStoreException, ClientException

说明

若请求中部分操作存在参数错误，服务端将抛出参数错误异常，整批操作均不执行。

以下示例向数据表 batch_write_demo 写入主键为 row1 的一行数据，并打印整体执行状态。

String tableName = "batch_write_demo";

BatchWriteRowRequest request = new BatchWriteRowRequest();

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"))
        .build();
RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"));
request.addRowChange(rowPutChange);

BatchWriteRowResponse response = client.batchWriteRow(request);
System.out.println("All Succeeded: " + response.isAllSucceed());
if (!response.isAllSucceed()) {
    for (BatchWriteRowResponse.RowResult fail : response.getFailedRows()) {
        System.out.println("Failed: table=" + fail.getTableName()
                + " index=" + fail.getIndex()
                + " error=" + fail.getError());
    }
}

参数说明

BatchWriteRowRequest 包含以下参数。

名称	类型	说明
rowChangesGroupByTable（必选）	`Map<String, List<RowChange>>`	按数据表组织的行操作，通过 `addRowChange` 添加。单次请求可跨表混合写入、更新和删除操作。
atomic（可选）	`Boolean`	是否启用批量原子写。启用后，同一数据表中的行操作必须使用相同主键，否则请求失败。
transactionId（可选）	`String`	局部事务 ID。仅在局部事务内操作数据时设置；设置后，单次请求只能包含一张数据表的操作。关于如何获取和使用该 ID，请参见局部事务。

行操作

rowChangesGroupByTable 中的每个元素为 RowChange，可使用以下实现类。

RowPutChange：写入一行中的属性列。具体配置请参见写入单行数据。
RowUpdateChange：新增、修改或删除一行中的属性列，也可执行原子计数。具体配置请参见更新单行数据。
RowDeleteChange：删除一行及其全部属性列数据。具体配置请参见删除单行数据。

返回值

BatchWriteRowResponse 包含以下业务字段。

字段	类型	说明
`tableToRowStatus`	`Map<String, List<RowResult>>`	按数据表组织的行级结果，通过 `getRowStatus` 获取。也可通过 `getSucceedRows` 和 `getFailedRows` 分别获取成功和失败的行级结果。

行级结果

tableToRowStatus 中的每个元素为 RowResult，包含以下字段。

字段	类型	说明
`isSucceed`	`boolean`	当前行操作是否成功。
`tableName`	`String`	数据表名称。
`error`	`Error`	当前行操作失败时的错误信息。
`index`	`int`	当前行操作在对应数据表操作列表中的位置。
`row`	`Row`	当前行操作返回的行数据。未配置返回内容时为 `null`。

场景示例

批量更新行数据

通过 RowUpdateChange 批量修改属性列。

String tableName = "batch_write_demo";

BatchWriteRowRequest request = new BatchWriteRowRequest();

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row_for_update"))
        .build();
RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);

// 修改或新增属性列
rowUpdateChange.put("col1", ColumnValue.fromString("new_val1"));
rowUpdateChange.put("col2", ColumnValue.fromLong(100));

// 删除整个属性列
rowUpdateChange.deleteColumns("obsolete_col");

request.addRowChange(rowUpdateChange);
client.batchWriteRow(request);

批量删除行数据

通过 RowDeleteChange 批量删除整行。

String tableName = "batch_write_demo";

BatchWriteRowRequest request = new BatchWriteRowRequest();

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row_for_delete"))
        .build();
RowDeleteChange rowDeleteChange = new RowDeleteChange(tableName, primaryKey);

request.addRowChange(rowDeleteChange);
client.batchWriteRow(request);

跨表混合多种操作

单次请求内对多张数据表混合执行写入、修改、删除等操作，结果按行独立返回。

String tableA = "batch_write_demo";
String tableB = "batch_write_demo_2";

BatchWriteRowRequest request = new BatchWriteRowRequest();

// 表 A 写入新行
PrimaryKey pkA = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("rowA_new"))
        .build();
RowPutChange putA = new RowPutChange(tableA, pkA);
putA.addColumn("col1", ColumnValue.fromString("valA"));
request.addRowChange(putA);

// 表 B 更新已有行
PrimaryKey pkB = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("rowB_existing"))
        .build();
RowUpdateChange updateB = new RowUpdateChange(tableB, pkB);
updateB.put("status", ColumnValue.fromString("done"));
request.addRowChange(updateB);

// 表 A 删除一行
PrimaryKey pkADel = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("rowA_obsolete"))
        .build();
RowDeleteChange deleteA = new RowDeleteChange(tableA, pkADel);
request.addRowChange(deleteA);

BatchWriteRowResponse response = client.batchWriteRow(request);

if (!response.isAllSucceed()) {
    System.out.println("Failed rows: " + response.getFailedRows().size());
    for (BatchWriteRowResponse.RowResult fail : response.getFailedRows()) {
        System.out.println(" - table=" + fail.getTableName()
                + " index=" + fail.getIndex()
                + " error=" + fail.getError().getMessage());
    }
}