Table Store Java SDK 批量資料操作 - 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());
    }
}