Batch read rows

Use Tablestore SDK for Python to read rows by primary key from one or more tables in a single request.

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Function description

Call batch_get_row to read multiple rows. The result of each row is returned independently.

def batch_get_row(self, request)

The following example reads two rows from example_table. Only the latest version of each attribute column is returned.

primary_keys = [
    [("partition", "device"), ("id", 1)],
    [("partition", "device"), ("id", 2)],
]
table_item = TableInBatchGetRowItem(
    "example_table",
    primary_keys,
    max_version=1,
)
request = BatchGetRowRequest()
request.add(table_item)

response = client.batch_get_row(request)
for item in response.get_succeed_rows():
    if item.row is not None:
        print(item.row.primary_key, item.row.attribute_columns)

Note

A single batch read supports up to 100 rows.

Parameters

The batch_get_row method contains the following parameter.

Name	Type	Description
request (required)	`BatchGetRowRequest`	The batch read request. Call `add` to add one `TableInBatchGetRowItem` for each table. Configurations are stored by table name. If the same table is added more than once, the latest configuration replaces the previous one.

Table read configurations

Each element in request.items[] is of the TableInBatchGetRowItem type and contains the following parameters. All rows in the same element share the attribute column, data version, and filter configurations.

Name	Type	Description
table_name (required)	`str`	The name of the table.
primary_keys (required)	`List[List[Tuple]]`	The primary keys to read. Each primary key must include all primary key columns and match the primary key schema of the table.
columns_to_get (optional)	`List[str]`	The primary key or attribute columns to return. If this parameter is omitted, entire rows are returned.
column_filter (optional)	`ColumnCondition`	The filter. For more information, see Use filters.
max_version (optional)	`int`	The maximum number of versions to return for each attribute column. You must specify either `max_version` or `time_range`. If more versions match, they are returned from newest to oldest.
time_range (optional)	`Tuple[int, int]`	The data version range in milliseconds. The start is inclusive, and the end is exclusive. This parameter and `max_version` are mutually exclusive.
start_column (optional)	`str`	The start attribute column for reading a wide row.
end_column (optional)	`str`	The end attribute column for reading a wide row.
token (optional)	`bytes`	The start position for the next page of a wide row.

Response

batch_get_row returns a BatchGetRowResponse. Use the following methods to obtain results.

Method	Return type	Description
`is_all_succeed()`	`bool`	Indicates whether all rows were read successfully.
`get_succeed_rows()`	`List[RowDataItem]`	The successful results. Each item contains the table name, row data, and consumed CUs. If the row does not exist, `row` is `None`.
`get_failed_rows()`	`List[RowDataItem]`	The failed results. Each item contains the table name, error code, and error message.
`get_result_by_table(table_name)`	`List[RowDataItem]`	The per-row results for the specified table.

Examples

Read rows from multiple tables

The following example reads two tables in one request. Each table uses a separate TableInBatchGetRowItem to configure the read.

request = BatchGetRowRequest()
request.add(
    TableInBatchGetRowItem(
        "example_table",
        [[("partition", "device"), ("id", 1)]],
        max_version=1,
    )
)
request.add(
    TableInBatchGetRowItem(
        "another_table",
        [[("partition", "order"), ("id", 1)]],
        max_version=1,
    )
)

response = client.batch_get_row(request)

Filter rows

The following example returns only rows whose latest value in the status attribute column is online. All primary keys for the same table share the filter.

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)
table_item = TableInBatchGetRowItem(
    "example_table",
    primary_keys,
    column_filter=column_filter,
    max_version=1,
)
request = BatchGetRowRequest()
request.add(table_item)

response = client.batch_get_row(request)