Document Center

BatchGetRow

Last Updated: Oct 11, 2016

BatchGetRow

Action:

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. }

tables

  • Type: repeated TableInBatchGetRowRequest

  • Required Parameter: Yes

  • Specifies the information of rows to be read.

  • If “tables” has the conditions described below, 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. }

tables

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 timeout 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.

Request Example:

  1. BatchGetRowRequest {
  2.   tables {
  3.     table_name: "consume_history"
  4.     rows {
  5.       primary_key {
  6.         name: "CardID"
  7.         value {
  8.           type: STRING
  9.           v_string: "2007035023"
  10.         }
  11.       }
  12.       primary_key {
  13.         name: "SellerID"
  14.         value {
  15.           type: STRING
  16.           v_string: "00022"
  17.         }
  18.       }
  19.       primary_key {
  20.         name: "DeviceID"
  21.         value {
  22.           type: STRING
  23.           v_string: "061104"
  24.         }
  25.       }
  26.       primary_key {
  27.         name: "OrderNumber"
  28.         value {
  29.           type: INTEGER
  30.           v_int: 142857
  31.         }
  32.       }
  33.     }
  34.     rows {
  35.       primary_key {
  36.         name: "CardID"
  37.         value {
  38.           type: STRING
  39.           v_string: "2007035023"
  40.         }
  41.       }
  42.       primary_key {
  43.         name: "SellerID"
  44.         value {
  45.           type: STRING
  46.           v_string: "00026"
  47.         }
  48.       }
  49.       primary_key {
  50.         name: "DeviceID"
  51.         value {
  52.           type: STRING
  53.           v_string: "065499"
  54.         }
  55.       }
  56.       primary_key {
  57.         name: "OrderNumber"
  58.         value {
  59.           type: INTEGER
  60.           v_int: 153846
  61.         }
  62.       }
  63.     }
  64.     columns_to_get: "CardID"
  65.     columns_to_get: "SellerID"
  66.     columns_to_get: "DeviceID"
  67.     columns_to_get: "OrderNumber"
  68.     columns_to_get: "Amount"
  69.     columns_to_get: "Remarks"
  70.   }
  71. }

Response Example:

  1. BatchGetRowResponse {
  2.   tables {
  3.     table_name: "consume_history"
  4.     rows {
  5.       is_ok: true
  6.       consumed {
  7.         capacity_unit {
  8.           read: 1
  9.         }
  10.       }
  11.       row {
  12.         primary_key_columns {
  13.           name: "CardID"
  14.           value {
  15.             type: STRING
  16.             v_string: "2007035023"
  17.           }
  18.         }
  19.         primary_key_columns {
  20.           name: "SellerID"
  21.           value {
  22.             type: STRING
  23.             v_string: "00022"
  24.           }
  25.         }
  26.         primary_key_columns {
  27.           name: "DeviceID"
  28.           value {
  29.             type: STRING
  30.             v_string: "061104"
  31.           }
  32.         }
  33.         primary_key_columns {
  34.           name: "OrderNumber"
  35.           value {
  36.             type: INTEGER
  37.             v_int: 142857
  38.           }
  39.         }
  40.         attribute_columns {
  41.           name: "Amount"
  42.           value {
  43.             type: DOUBLE
  44.             v_double: 2.5
  45.           }
  46.         }
  47.         attribute_columns {
  48.           name: "Remarks"
  49.           value {
  50.             type: STRING
  51.             v_string: "ice cream"
  52.           }
  53.         }
  54.       }
  55.     }
  56.     rows {
  57.       is_ok: true
  58.       consumed {
  59.         capacity_unit {
  60.           read: 1
  61.         }
  62.       }
  63.       row {
  64.         primary_key_columns {
  65.           name: "CardID"
  66.           value {
  67.             type: STRING
  68.             v_string: "2007035023"
  69.           }
  70.         }
  71.         primary_key_columns {
  72.           name: "SellerID"
  73.           value {
  74.             type: STRING
  75.             v_string: "00026"
  76.           }
  77.         }
  78.         primary_key_columns {
  79.           name: "DeviceID"
  80.           value {
  81.             type: STRING
  82.             v_string: "065499"
  83.           }
  84.         }
  85.         primary_key_columns {
  86.           name: "OrderNumber"
  87.           value {
  88.             type: INTEGER
  89.             v_int: 153846
  90.           }
  91.         }
  92.         attribute_columns {
  93.           name: "Amount"
  94.           value {
  95.             type: DOUBLE
  96.             v_double: 0.5
  97.           }
  98.         }
  99.       }
  100.     }
  101.   }
  102. }
Thank you! We've received your feedback.
Free Trial Free Trial