Insert, modify, or delete multiple rows of data from one or more tables at the same time - Tablestore

BatchWriteRow is a composite operation that bundles PutRow, UpdateRow, and DeleteRow calls into a single request. Each sub-operation is executed and billed independently, and each has its own response entry.

Compared to calling PutRow, UpdateRow, or DeleteRow individually, BatchWriteRow reduces round-trip latency and improves write throughput.

Request syntax

message BatchWriteRowRequest {
    repeated TableInBatchWriteRowRequest tables = 1;
    optional string transaction_id = 2;
    optional bool is_atomic = 3;
}

Parameter	Type	Required	Description
tables	TableInBatchWriteRowRequest	Yes	The rows on which to perform the batch write operation. The request fails if any of the following conditions exist: A specified table does not exist. Multiple tables with the same name are specified. A table name does not comply with the naming conventions. For more information, see Naming conventions and data types. A row is missing its primary key, or has a primary key column with a non-compliant name or invalid type. An attribute column name in a row does not comply with the naming conventions. For more information, see Naming conventions and data types. An attribute column name in a row conflicts with a primary key column name. A primary key column value or attribute column value exceeds the size limit. For more information, see General limits. Multiple rows in a table share the same primary key. The total number of rows exceeds 200, or the total data size exceeds 4 MB. A specified table does not contain the rows on which you want to perform operations. In this case, the OTSParameterInvalidException error is returned. The number of columns in a PutRowInBatchWriteRowRequest for a table exceeds 1,024. The number of columns specified by the ColumnUpdate parameter in an UpdateRowInBatchWriteRowRequest for a table exceeds 1,024.
transaction_id	string	No	The local transaction ID. Required when using the local transaction feature to write data in batches.
is_atomic	bool	No	Specifies whether to execute the batch write as atomic operations.

Response syntax

Note

BatchWriteRow can partially fail at the row level while still returning HTTP 200. Check is_ok in each RowInBatchWriteRowResponse entry to confirm the result for each row and handle failures accordingly.

message BatchWriteRowResponse {
    repeated TableInBatchWriteRowResponse tables = 1;
}

Parameter

Type

Description

tables

TableInBatchWriteRowResponse

The result for each operation in each table, including execution status, error codes, and CUs consumed.

The order of TableInBatchWriteRowResponse entries matches the order of TableInBatchWriteRowRequest entries in the request. Within each table, the order of RowInBatchWriteRowResponse entries in put_rows, update_rows, and delete_rows matches the order of the corresponding PutRowInBatchWriteRowRequest, UpdateRowInBatchWriteRowRequest, and DeleteRowInBatchWriteRowRequest entries.

If a row operation fails, is_ok in its RowInBatchWriteRowResponse entry is false.

Use Tablestore SDKs

The following Tablestore SDKs support batch write operations:

Tablestore SDK for Java: Write multiple rows of data in a batch
Tablestore SDK for Go: Write multiple rows of data in a batch
Tablestore SDK for Python: Write multiple rows of data in a batch
Tablestore SDK for Node.js: Write multiple rows of data in a batch
Tablestore SDK for .NET: Write multiple rows of data in a batch
Tablestore SDK for PHP: Write multiple rows of data in a batch

CU consumption

If the operation fails, no CUs are consumed.
If the request times out and the results are undefined, CUs may or may not be consumed.
In other scenarios, each PutRowInBatchWriteRowRequest, UpdateRowInBatchWriteRowRequest, or DeleteRowInBatchWriteRowRequest is treated as an independent PutRow, UpdateRow, or DeleteRow operation with separately calculated CUs. For more information, see PutRow, UpdateRow, and DeleteRow.