Last Updated: Sep 07, 2017


Batch reads several data rows from one or more tables.

The BatchGetRow operation can be viewed as a set of multiple GetRow operations. Each operation is independently executed, returns results independently and independently consumes capacity units.

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

Request Structure:

  1. message BatchGetRowRequest {
  2. repeated TableInBatchGetRowRequest tables = 1;
  3. }


  • Type: repeated TableInBatchGetRowRequest

  • Required Parameter: Yes

  • Specifies the information of rows to be read.

  • If “tables” has the conditions described as follows, the entire operation will fail and return an error.

    • Any table in “tables” does not exist.

    • 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 name does not comply with the conventions, or the primary key type is incorrect.

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

    • “Tables” contains tables with the same name.

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

    • In “tables”, the total number of RowInBatchGetRowRequest exceeds 100.

    • Any table in “tables” does not contain any RowInBatchGetRowRequest.

    • Columns_to_get for any table in “tables” exceeds 128 columns.

Response message structure:

  1. message BatchGetRowResponse {
  2. repeated TableInBatchGetRowResponse tables = 1;
  3. }


  • Type: repeated TableInBatchGetRowResponse

  • Corresponds to the data to be read in each table.

  • The TableInBatchGetRowResponse object order in the response message is the same as the TableInBatchGetRowRequest object order in BatchGetRowRequest. The order of each RowInBatchGetRowResponse under TableInBatchGetRowResponse is the same as that of RowInBatchGetRowRequest under TableInBatchGetRowRequest.

  • If a row does not exist or does not have data in the specified columns_to_get, a corresponding RowInBatchGetRowResponse will still appear in TableInBatchGetRowResponse, but the row’s primary_key_columns and attribute_columns will be null.

  • If a row fails to be read, the is_ok value in RowInBatchGetRowResponse for the row will be false and the row will be null.

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

Capacity unit consumption:

  • If the entire operation fails, it will 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 RowInBatchGetRowRequest operation is viewed as one GetRow operation when write capacity units are counted.

Thank you! We've received your feedback.