Last Updated: Dec 27, 2017


Batch inserts, modifies, or deletes several data rows in one or more tables.

The BatchWriteRow operation can be viewed as a set of multiple PutRow, UpdateRow, and DeleteRow operations. Each operation is executed and returns results independently and independently consumes capacity units.

Compared to the execution of a large number of write operations, the use of the BatchWriteRow operation can effectively reduce the request response time and increase the data write rate.

Request structure:

  1. message BatchWriteRowRequest {
  2. repeated TableInBatchWriteRowRequest tables = 1;
  3. }


  • Type: repeated TableInBatchWriteRowRequest

  • Required parameter: Yes

  • Specifies the information of rows that require write operations.

  • In the following cases, a general error is returned:

    • Any table in “tables” does not exist.

    • “Tables” contains tables with the same name.

    • The name of any table in “tables” does not comply with the Table naming conventions.

    • The primary key is not specified for any row in “tables”, the primary key column name does not comply with the conventions, or the primary key column type is incorrect.

    • For any attribute column in “tables”, the column name does not comply with the Column naming conventions.

    • Any row in “tables” has an attribute column with the same name as the primary key column.

    • The value of any primary key or attribute column in “tables” exceeds the Restricted items.

    • Any table in “tables” contains rows with identical primary keys.

    • The total number of rows for all tables in “tables” exceeds 200 or the total size of the data contained exceeds 1M.

    • If any table in “tables” contains no rows, the OTSParameterInvalidException error is returned

    • In “tables”, any PutRowInBatchWriteRowRequest contains more than 1024 columns.

    • In “tables”, any UpdateRowInBatchWriteRowRequest contains more than 1024 ColumnUpdate objects.

Response message structure:

  1. message BatchWriteRowResponse {
  2. repeated TableInBatchWriteRowResponse tables = 1;
  3. }


  • Type: TableInBatchWriteRowResponse

  • The response information corresponding to the operations for each table, including whether or not execution was successful, error codes, and the capacity units consumed.

  • The TableInBatchWriteRowResponse object order in the response message is the same as the TableInBatchWriteRowRequest object order in BatchWriteRowRequest. The RowInBatchWriteRowResponse object orders contained in put_rows, update_rows, and delete_rows in each TableInBatchWriteRowRequest are the same as the respective PutRowInBatchWriteRowRequest, UpdateRowInBatchWriteRowRequest, and DeleteRowInBatchWriteRowRequest object orders contained in put_rows, update_rows, and delete_rows in TableInBatchWriteRowRequest.

  • If a row fails to be read, the row’s is_ok value in RowInBatchWriteRowResponse is false.

Note: The BatchWriteRow operation may fail partly at the row level. In this case, it still returns an HTTP status code of 200. The application must check errors in RowInBatchWriteRowResponse to confirm the execution results for each row and then proceed accordingly.

Capacity unit consumption:

  • If the entire operation fails, it does not consume any capacity units.

  • If request time-out occurs and the results are undefined, a capacity unit may or may not be consumed.

  • In other situations, each PutRowInBatchWriteRowRequest, UpdateRowInBatchWriteRowRequestDelete, and RowInBatchWriteRowRequest operation is viewed as a corresponding write operation when the number of write capacity units are counted.

Thank you! We've received your feedback.