Batch row operations

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Description

Call batchWriteRow to mix write, update, and delete row operations across tables in a single request. The server processes each row independently. A failure on one row does not affect the other rows. Call isAllSucceed and getFailedRows to inspect the results.

public BatchWriteRowResponse batchWriteRow(BatchWriteRowRequest batchWriteRowRequest) throws TableStoreException, ClientException

Note

If any operation in the request contains a parameter error, Tablestore returns a parameter error for the entire request and no operations run.

The following example writes one row (primary key row1) to the table batch_write_demo, checks the overall result with isAllSucceed, and retrieves failed-row details with getFailedRows.

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());
    }
}

Parameters

BatchWriteRowRequest contains the following parameters.

Name	Type	Description
rowChangesGroupByTable (required)	`Map<String, List<RowChange>>`	The row operations grouped by table, added by calling `addRowChange`. A single request can mix write, update, and delete operations across tables.
atomic (optional)	`Boolean`	Specifies whether to enable batch atomic writes. If enabled, row operations for the same table must use the same primary key. Otherwise, the request fails.
transactionId (optional)	`String`	The local transaction ID. Set this parameter only when you operate on data in a local transaction. If it is set, a single request can contain operations for only one table. For information about how to obtain and use the ID, see Use local transactions.

Row operations

Each element in rowChangesGroupByTable is a RowChange implementation. The following implementations are supported.

RowPutChange: Writes attribute columns to a row. For configuration details, see Write a row.
RowUpdateChange: Adds, modifies, or deletes attribute columns in a row, or performs atomic increments. For configuration details, see Update a row.
RowDeleteChange: Deletes a row and all of its attribute column data. For configuration details, see Delete a row.

Response

BatchWriteRowResponse contains the following operation-specific field.

Field	Type	Description
`tableToRowStatus`	`Map<String, List<RowResult>>`	The row-level results grouped by table, obtained by calling `getRowStatus`. You can also call `getSucceedRows` and `getFailedRows` to obtain the successful and failed row results.

Row result

Each element in tableToRowStatus is of the RowResult type and contains the following fields.

Field	Type	Description
`isSucceed`	`boolean`	Indicates whether the row operation succeeded.
`tableName`	`String`	The name of the table.
`error`	`Error`	The error information returned when the row operation fails.
`index`	`int`	The position of the row operation in the operation list for the table.
`row`	`Row`	The row data returned by the operation. If no return content is configured, the value is `null`.

Examples

Batch update rows

Use RowUpdateChange to update attribute columns in a batch request.

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);

// Update or add attribute columns
rowUpdateChange.put("col1", ColumnValue.fromString("new_val1"));
rowUpdateChange.put("col2", ColumnValue.fromLong(100));

// Delete an entire attribute column
rowUpdateChange.deleteColumns("obsolete_col");

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

Batch delete rows

Use RowDeleteChange to delete entire rows in a batch request.

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);

Mix operations across tables

Mix write, update, and delete operations across multiple tables in a single request. Tablestore returns results per row.

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

BatchWriteRowRequest request = new BatchWriteRowRequest();

// Insert a new row into table 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);

// Update an existing row in table 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);

// Delete a row from table 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());
    }
}