Read a range of rows

Use Tablestore SDK for Python to read contiguous rows in a primary key range and optionally specify the direction, pagination, data versions, or a filter.

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Function description

Call get_range to read rows in a primary key range. The start primary key is included, and the end primary key is excluded.

def get_range(
    self,
    table_name,
    direction,
    inclusive_start_primary_key,
    exclusive_end_primary_key,
    columns_to_get=None,
    limit=None,
    column_filter=None,
    max_version=1,
    time_range=None,
    start_column=None,
    end_column=None,
    token=None,
    transaction_id=None,
)

The following example reads all rows in the device partition of example_table in the forward direction. Only the latest version of each attribute column is returned.

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

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
)
for row in rows:
    print(row.primary_key, row.attribute_columns)

Note

A single range read returns up to 5,000 rows or 4 MB of data. If the limit is reached, use next_start_primary_key in the response to continue reading.

Parameters

The get_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.
columns_to_get (optional)	`List[str]`	The primary key or attribute columns to return. If this parameter is omitted, entire rows are returned.
limit (optional)	`int`	The maximum number of rows to return in one request. The value must be greater than `0`. If the limit is reached, use `next_start_primary_key` to continue reading.
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 the next page of a wide row. Use the `next_token` returned by the previous request.
transaction_id (optional)	`str`	The local transaction ID. Specify this parameter only for reads in a local transaction. For more information, see Use local transactions.

Response

get_range returns the following values.

Field	Type	Description
consumed	`CapacityUnit`	The read and write CUs consumed by the operation.
next_start_primary_key	`List[Tuple]`	The start primary key for the next page. A value of `None` indicates that all rows in the primary key range have been read.
rows	`List[Row]`	The rows that meet the conditions.
next_token	`bytes`	The start position for the next page of a wide row. A value of `None` indicates that all attribute columns in the current row have been read.

Examples

Read all pages

The following example repeatedly uses next_start_primary_key until all rows in the primary key range are read.

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

while start_primary_key:
    consumed, start_primary_key, rows, next_token = client.get_range(
        "example_table",
        Direction.FORWARD,
        start_primary_key,
        end_primary_key,
        limit=100,
    )

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

Read in the backward direction

For a backward read, the start primary key must be greater than the end primary key.

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

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.BACKWARD,
    start_primary_key,
    end_primary_key,
)

Filter rows

The following example returns only rows whose latest value in the status attribute column is online.

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    column_filter=column_filter,
)