Inserts, modifies, or deletes multiple rows of data from one or more tables at the same time.

The BatchWriteRow operation is a set of PutRow, UpdateRow, or DeleteRow operations. If you call the BatchWriteRow operation, each PutRow, UpdateRow, or DeleteRow operation is separately performed, the response to each PutRow, UpdateRow, or DeleteRow operation is separately returned, and consumption units (CUs) are separately calculated for each PutRow, UpdateRow, or DeleteRow operation.

If you call the BacthWriteRow operation instead of calling the PutRow, UpdateRow, or DeleteRow operation multiple times, the response time is reduced, and the data write performance is improved.

Request syntax

message BatchWriteRowRequest {
    repeated TableInBatchWriteRowRequest tables = 1;
}
Parameter Type Required Description
tables TableInBatchWriteRowRequest Yes The rows on which you want to perform the batch write operation.

If one of the following conditions is met, an error is returned:

  • A specified table does not exist.
  • Tables with the same names are specified.
  • The name of a specified table does not comply with the naming conventions. For more information, see Naming conventions and data types.
  • The primary key is not specified, the name of a primary key column does not comply with the naming conventions, or the type of a primary key column is invalid for a specified row.
  • The name of an attribute column in a specified row does not comply with the naming conventions. For more information, see Naming conventions and data types.
  • The name of an attribute column in a specified row is the same as the name of a primary key column in the row.
  • The value of a primary key column or an attribute column in a specified row exceeds the upper limit in size. For more information, see General limits.
  • The rows whose primary keys are the same exist in a specified table.
  • The total number of specified rows exceeds 200, or the total size of data in specified rows exceeds 4 MB.
  • If a specified table does not contain the rows on which you want to perform operations, the OTSParameterInvalidException error is returned.
  • The number of columns that are included in the PutRowInBatchWriteRowRequest method for a specified table exceeds 1,024.
  • The number of columns that are specified by using the ColumnUpdate parameter in the UpdateRowInBatchWriteRowRequest method for a specified table exceeds 1,024.

Response syntax

Note The BatchWriteRow operation may partially fail at the row level. However, the operation still returns the HTTP 200 status code. The application must check errors in RowInBatchWriteRowResponse to confirm the execution result for each row and then proceed accordingly. 
message BatchWriteRowResponse {
    repeated TableInBatchWriteRowResponse tables = 1;
}
Parameter Type Description
tables TableInBatchWriteRowResponse The response to each operation for each table. The response contains the execution results, error codes, and the number of consumed CUs.

The order of the TableInBatchWriteRowResponse methods in the response is the same as the order of the TableInBatchWriteRowRequest methods in BatchWriteRowRequest. The order of the RowInBatchWriteRowResponse methods that are contained in put_rows, update_rows, or delete_rows in each TableInBatchWriteRowRequest method is the same as the order of the PutRowInBatchWriteRowRequest, UpdateRowInBatchWriteRowRequest, or DeleteRowInBatchWriteRowRequest methods that are contained in put_rows, update_rows, or delete_rows in TableInBatchWriteRowRequest.

If a row fails to be read, the value of is_ok in RowInBatchWriteRowResponse is false for the row.

Use Tablestore SDKs

You can use the following Tablestore SDKs to insert, modify, or delete multiple rows of data from one or more tables at the same time:

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 method is considered a PutRow, UpdateRow, or DeleteRow operation for which CUs are separately calculated. For more information, see PutRow, UpdateRow, and DeleteRow.