表格存储 Python SDK 范围读取数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Python SDK 按主键范围读取连续多行数据，并按需设置读取方向、分页、数据版本和过滤条件。

前提条件

功能说明

调用 get_range 方法按主键范围读取数据。返回范围包含起始主键，不包含结束主键。

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,
)

以下示例正向读取 example_table 中 device 分区内的所有行，仅返回每个属性列的最新版本。

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)

说明

单次范围读取最多返回 5000 行或 4 MB 数据。超出限制时，使用响应中的 next_start_primary_key 继续读取。

参数说明

get_range 方法包含以下参数。

名称	类型	说明
table_name（必选）	`str`	数据表名称。
direction（必选）	`Direction`	读取方向。`FORWARD` 表示正向读取；`BACKWARD` 表示反向读取。
inclusive_start_primary_key（必选）	`List[Tuple]`	起始主键，返回结果包含该主键。正向读取时必须小于结束主键，反向读取时必须大于结束主键。主键结构必须与数据表一致。
exclusive_end_primary_key（必选）	`List[Tuple]`	结束主键，返回结果不包含该主键。主键结构必须与数据表一致。
columns_to_get（可选）	`List[str]`	要返回的主键列或属性列名称。不设置时返回整行。
limit（可选）	`int`	单次请求最多返回的行数，必须大于 `0`。达到该值时，使用 `next_start_primary_key` 继续读取。
column_filter（可选）	`ColumnCondition`	过滤条件。有关配置方法，请参见过滤器。
max_version（可选）	`int`	每个属性列最多返回的版本数，默认值为 `1`。如果符合条件的版本数超过该值，按从新到旧的顺序返回。`max_version` 和 `time_range` 必须设置其中一个；设置 `time_range` 时，将 `max_version` 设置为 `None`。
time_range（可选）	`Tuple[int, int]`	数据版本范围，单位为毫秒，左闭右开。与 `max_version` 二选一。
start_column（可选）	`str`	宽行读取的起始属性列名称。
end_column（可选）	`str`	宽行读取的结束属性列名称。
token（可选）	`bytes`	宽行分页读取的起始位置。值来自上一次请求返回的 `next_token`。
transaction_id（可选）	`str`	局部事务 ID。仅在局部事务内读取数据时设置。有关使用方法，请参见局部事务。

返回值

get_range 返回以下值。

字段	类型	说明
consumed	`CapacityUnit`	本次操作消耗的读写 CU。
next_start_primary_key	`List[Tuple]`	下一页的起始主键。返回 `None` 表示主键范围内的行已全部读取。
rows	`List[Row]`	符合条件的行数据。
next_token	`bytes`	宽行分页读取的下一页起始位置。返回 `None` 表示当前行的属性列已全部读取。

场景示例

分页迭代读取

以下示例循环使用 next_start_primary_key，直到读取完指定主键范围内的所有行。

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)

反向读取

反向读取时，起始主键必须大于结束主键。

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,
)

条件过滤读取

以下示例只返回 status 属性列的最新值为 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,
)