表格存储 Python SDK 读取单行数据 - 表格存储

使用 Python SDK 按主键读取单行数据，并按需指定属性列、数据版本范围和过滤条件。

前提条件

功能说明

调用 get_row 方法读取单行数据。

def get_row(
    self,
    table_name,
    primary_key,
    columns_to_get=None,
    column_filter=None,
    max_version=1,
    time_range=None,
    start_column=None,
    end_column=None,
    token=None,
    transaction_id=None,
)

以下示例读取 example_table 中主键为 ("device", 1) 的一行数据，仅返回每个属性列的最新版本。

primary_key = [("partition", "device"), ("id", 1)]

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
)
if return_row is not None:
    print(return_row.primary_key)
    print(return_row.attribute_columns)

参数说明

get_row 方法包含以下参数。

名称	类型	说明
table_name（必选）	`str`	数据表名称。
primary_key（必选）	`List[Tuple]`	主键信息。必须包含全部主键列，且主键列的名称、顺序、数量和类型与数据表的主键结构一致。
columns_to_get（可选）	`List[str]`	要返回的主键列或属性列名称。不设置时返回整行；设置后，如果目标行不包含任何指定的属性列，则 `return_row` 为 `None`。
column_filter（可选）	`ColumnCondition`	过滤条件。有关配置方法，请参见过滤器。同时设置 `columns_to_get` 和 `column_filter` 时，先选择要返回的列，再按条件过滤。
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_row 返回以下值。

字段	类型	说明
consumed	`CapacityUnit`	本次操作消耗的读写 CU。
return_row	`Row`	返回的行数据。目标行不存在、未通过过滤条件或不包含任何指定的属性列时为 `None`。
next_token	`bytes`	宽行分页读取的下一页起始位置。返回 `None` 表示当前行的属性列已全部读取。

场景示例

指定读取的属性列

以下示例只返回 status 和 temperature 属性列。

primary_key = [("partition", "device"), ("id", 1)]
columns_to_get = ["status", "temperature"]

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
    columns_to_get=columns_to_get,
)

指定数据版本范围

以下示例返回过去一天内写入的所有版本数据。

end_time = int(time.time() * 1000)
start_time = end_time - 86400 * 1000
primary_key = [("partition", "device"), ("id", 1)]

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
    max_version=None,
    time_range=(start_time, end_time),
)

条件过滤读取

以下示例仅在 status 属性列的最新值为 online 时返回该行。

primary_key = [("partition", "device"), ("id", 1)]
column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
    column_filter=column_filter,
)