Reads multiple rows of data from one or more tables at the same time.

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

If you call the BacthGetRow operation instead of calling the GetRow operation multiple times, the response time is reduced, and the data read performance is improved.

Request syntax

message BatchGetRowRequest {
    repeated TableInBatchGetRowRequest tables = 1;
}           
ParameterTypeRequiredDescription
tablesrepeated TableInBatchGetRowRequestYesThe rows that you want to read from each table.

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

  • A specified table does not exist.
  • 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 a column that is specified by using the columns_to_get parameter in a specified table does not comply with the naming conventions. For more information, see Naming conventions and data types.
  • Tables with the same names are specified.
  • The number of RowInBatchGetRowRequest methods for all specified tables exceeds 100.
  • The RowInBatchGetRowRequest method is not specified for a specified table.
  • The number of columns that are specified by using the columns_to_get parameter exceeds 128 for a specified table.

Response syntax

Note The BatchGetRow operation may partially fail at the row level. However, the operation still returns the HTTP 200 status code. The application must check errors in RowInBatchGetRowResponse to confirm the execution result for each row and then proceed accordingly.
message BatchGetRowResponse {
    repeated TableInBatchGetRowResponse tables = 1;
}          
ParameterTypeDescription
tablesrepeated TableInBatchGetRowResponseThe rows that are read from each table.

The order of the TableInBatchGetRowResponse methods in the response is the same as the order of the TableInBatchGetRowRequest methods in BatchGetRowRequest. The order of the RowInBatchGetRowResponse methods in TableInBatchGetRowResponse is the same as the order of the RowInBatchGetRowRequest methods in TableInBatchGetRowRequest.

If a row does not exist or if the columns that are specified by using the columns_to_get parameter in a row are empty, the RowInBatchGetRowResponse method still appears in the TableInBatchGetRowResponse method, but the primary_key_columns and attribute_columns parameters for the row are empty.

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

Use Tablestore SDKs

You can use the following Tablestore SDKs to read 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 RowInBatchGetRowRequest method is considered a GetRow operation for which the write CUs are separately calculated. For more information, see GetRow.