All Products
Search

This Product

    Tablestore:Batch get data

    Document Center

    Tablestore:Batch get data

    Last Updated:Mar 31, 2026

    Batch read data from one or more Tablestore tables by using the Python SDK.

    Usage notes

    Each batch get operation can retrieve up to 100 rows.

    Prerequisites

    Initialize the Tablestore Client

    Method

    def batch_get_row(self, request)

    Request parameters

    • items (Required)List[TableInBatchGetRowItem]: A list of items to retrieve in a batch get operation. Each item contains 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 the number of matching versions exceeds this limit, Tablestore returns the most recent versions up to this limit in reverse chronological order.

      time_range (Optional)

      Tuple

      The version range of the data to read.

      • You must specify either max_version or time_range.

      • Each attribute column in a Tablestore table can contain multiple data versions. Setting a version range returns only the versions that fall within that range.

      columns_to_get (Optional)

      List[str]

      The columns to read. These can be primary key columns or attribute columns.

      • If this parameter is not specified, the entire row is returned.

      • If the row does not contain any of the specified columns, the response returns null.

      column_filter (Optional)

      ColumnCondition

      The filter condition. For more information, see filter.

      • If both columns_to_get and column_filter are specified, Tablestore first retrieves the columns specified in columns_to_get, then applies the column_filter to filter the results.

    Sample code

    The following code reads two rows with the primary key values row1 and row2 from the test_table 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)

    The following examples demonstrate additional parameter configurations for batch get operations.

    • Read data from multiple tables. A batch get operation supports reading from multiple tables. Specify 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 the data versions that fall 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 the 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