Read rows with an iterator

Tablestore SDK for Python can read rows within a primary key range with an iterator and automatically continue reading subsequent pages.

Prerequisites

Install the Tablestore SDK for Python and initialize the client.

Feature description

Call xget_range to create a range iterator. The iterator returns rows between the start and end primary keys in the specified direction. The start primary key is included, and the end primary key is excluded. The SDK uses the start primary key returned for each subsequent page until the specified range is read or the number of rows specified by count is reached.

def xget_range(
    self,
    table_name,
    direction,
    inclusive_start_primary_key,
    exclusive_end_primary_key,
    consumed_counter,
    columns_to_get=None,
    count=None,
    column_filter=None,
    max_version=1,
    time_range=None,
    start_column=None,
    end_column=None,
    token=None,
)

The following example iterates over all rows in the device partition of example_table in the forward direction and accumulates the consumed read CUs.

start_primary_key = [("partition", "device"), ("id", INF_MIN)]
end_primary_key = [("partition", "device"), ("id", INF_MAX)]
consumed_counter = CapacityUnit(0, 0)

rows = client.xget_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    consumed_counter,
    columns_to_get=["category"],
)

for row in rows:
    print(row.primary_key, row.attribute_columns)

print("Read CU: %s" % consumed_counter.read)

Parameters

The xget_range method contains the following parameters.

Name	Type	Description
table_name (required)	`str`	The name of the table.
direction (required)	`Direction`	The read direction. `FORWARD` reads in the forward direction, and `BACKWARD` reads in the backward direction.
inclusive_start_primary_key (required)	`List[Tuple]`	The start primary key, which is included in the result. It must be less than the end primary key for a forward read and greater than the end primary key for a backward read. Its schema must match that of the table.
exclusive_end_primary_key (required)	`List[Tuple]`	The end primary key, which is excluded from the result. Its schema must match that of the table.
consumed_counter (required)	`CapacityUnit`	The CU counter. Pass `CapacityUnit(0, 0)`. The SDK accumulates read CUs as the iterator is consumed.
columns_to_get (optional)	`List[str]`	The primary key or attribute columns to return. If this parameter is omitted, entire rows are returned.
count (optional)	`int`	The maximum number of rows to read during the iteration. The value must be greater than `0`. If this parameter is omitted, all rows in the specified primary key range are read.
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. Default value: `1`. If more versions match, they are returned from newest to oldest. You must specify either `max_version` or `time_range`. To use `time_range`, set `max_version` to `None`.
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 reading a wide row. Use the `next_token` returned by a previous range read.

Response

xget_range returns an Iterator[Row]. Each iteration returns a Row object that contains primary key and attribute columns. After the iterator is consumed, consumed_counter.read contains the total read CUs consumed by the iteration.