All Products
Search

This Product

    Tablestore:Batch get data

    Document Center

    Tablestore:Batch get data

    Last Updated:Jun 03, 2026

    Read rows from one or more Tablestore tables in a single batch request.

    Usage notes

    A single batch request retrieves up to 100 rows.

    Prerequisites

    Initialize the Tablestore Client

    Method

    def batch_get_row(self, request)

    Request parameters

    • items (Required)List[TableInBatchGetRowItem]: The batch get items. Each item accepts the following parameters.

      Parameter

      Type

      Description

      table_name (Required)

      str

      The name of the table.

      primary_keys (Required)

      List[Tuple]

      The name and value of each primary key column.

      • The data type of a primary key column can be STRING, INTEGER, or BINARY.

      • The number and types of primary key columns must match the table's schema.

      max_version (Optional)

      int

      The maximum number of versions to return.

      • You must specify either max_version or time_range.

      • If more versions exist, Tablestore returns the most recent ones in reverse chronological order, up to this limit.

      time_range (Optional)

      Tuple

      The version range of the data to read.

      • You must specify either max_version or time_range.

      • Attribute columns can have multiple versions. Only versions within the specified range are returned.

      columns_to_get (Optional)

      List[str]

      The primary key or attribute columns to read.

      • If not specified, all columns are returned.

      • Returns null if the row contains none of the specified columns.

      column_filter (Optional)

      ColumnCondition

      The column filter applied to results.

      • When both are specified, Tablestore retrieves columns_to_get first, then applies column_filter.

    Sample code

    Read two rows (row1 and row2) from test_table:

    try:
    primary_keys = []
    # Add the primary key for the first row.
    primary_keys.append([('id', 'row1')])
    # Add the primary key for the second row.
    primary_keys.append([('id', 'row2')])

    # Construct the query condition.
    batchGetRowItem = TableInBatchGetRowItem('test_table', primary_keys=primary_keys, max_version=1)

    # Call the batch_get_row method to perform a batch get operation.
    request = BatchGetRowRequest()
    request.add(batchGetRowItem)
    response = client.batch_get_row(request)

    # Process the response.
    print('* Is all succeeded: %s' % response.is_all_succeed())
    print('* Succeeded Rows: ')
    for succeed in response.get_succeed_rows():
        if succeed.row is not None:
            print('table_name: %s. primary_key: %s, attribute_columns: %s.' % (succeed.table_name, succeed.row.primary_key,
                                                                               succeed.row.attribute_columns))
        else:
            print('table_name: %s. This row does not exist.' % succeed.table_name)
    if not response.is_all_succeed():
        print('* Failed Rows: ')
        for failed in response.get_failed_rows():
            print('table_name: %s. error code: %s, error message: %s.' % (failed.table_name, failed.error_code,
                                                                          failed.error_message))
except Exception as e:
    print("Batch get row failed with error: %s" % e)

    Additional parameter examples:

    • Read from multiple tables by adding a TableInBatchGetRowItem for each table.

      # Construct the query condition for the second table.
primary_keys1 = [[('order_id', '90fb478c-1360-11f0-a34d-00163e30a2a9')]]
batchGetRowItem1 = TableInBatchGetRowItem('orders_small', primary_keys=primary_keys1, max_version=1)
request.add(batchGetRowItem1)

    • Set a version range to read only versions within that range.

      # Set the version range to the last 24 hours from the current time.
time_range = (int(time.time() * 1000 - 86400 * 1000), int(time.time() * 1000))
batchGetRowItem = TableInBatchGetRowItem('test_table', primary_keys=primary_keys, time_range=time_range)

    • Specify which attribute columns to read.

      columns_to_get = ['col1']
batchGetRowItem = TableInBatchGetRowItem('test_table', primary_keys=primary_keys, columns_to_get=columns_to_get, max_version=1)

    Related topics

    Read data in a range