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

Python SDK 可通过迭代器读取指定主键范围内的多行数据，并自动读取后续分页。

前提条件

功能说明

调用 xget_range 方法创建范围迭代器。迭代器按照指定方向逐行返回起始主键和结束主键之间的数据，起始主键包含在结果中，结束主键不包含在结果中。SDK 根据每次请求返回的下一页起始主键继续读取，直到完成指定范围的读取或达到 count 设置的行数。

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

以下示例正向迭代读取 example_table 中 device 分区内的所有行，并累计读取消耗的 CU。

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)

参数说明

xget_range 方法包含以下参数。

名称	类型	说明
table_name（必选）	`str`	数据表名称。
direction（必选）	`Direction`	读取方向。`FORWARD` 表示正向读取；`BACKWARD` 表示反向读取。
inclusive_start_primary_key（必选）	`List[Tuple]`	起始主键，返回结果包含该主键。正向读取时必须小于结束主键，反向读取时必须大于结束主键。主键结构必须与数据表一致。
exclusive_end_primary_key（必选）	`List[Tuple]`	结束主键，返回结果不包含该主键。主键结构必须与数据表一致。
consumed_counter（必选）	`CapacityUnit`	CU 计数器。传入 `CapacityUnit(0, 0)`，SDK 在遍历迭代器时累计读 CU。
columns_to_get（可选）	`List[str]`	要返回的主键列或属性列名称。不设置时返回整行。
count（可选）	`int`	本次迭代最多读取的行数，必须大于 `0`。不设置时读取指定主键范围内的所有行。
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`。

返回值

xget_range 返回 Iterator[Row]。迭代器每次返回一个 Row 对象，其中包含主键列和属性列。完成迭代后，可通过 consumed_counter.read 获取本次迭代累计消耗的读 CU。