表格存储 Python SDK 范围读取数据 - 表格存储

本文介绍如何通过 Python SDK 范围读取表格存储中的数据。

前提条件

方法说明

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

参数说明

名称	类型	说明
table_name（必选）	str	数据表名称。
inclusive_start_primary_key（必选）	List[Tuple]	起始主键信息，包括主键列名称和主键值。返回数据包含起始主键。主键个数和类型必须与数据表的主键保持一致。正向读取数据时，起始主键必须小于结束主键。反向读取数据时，起始主键必须大于结束主键。 INF_MIN 表示无限小，INF_MAX 表示无限大。
exclusive_end_primary_key（必选）	List[Tuple]	结束主键信息，包括主键列名称和主键值。返回数据不包含结束主键。主键个数和类型必须与数据表的主键保持一致。 INF_MIN 表示无限小，INF_MAX 表示无限大。
direction（必选）	Direction	读取方向。 FORWARD：默认值，正向读取数据。 BACKWARD：反向读取数据。
max_version（可选）	int	最大版本数，默认值为1。必须设置最大版本数和版本范围的其中一个。如果符合查询条件的数据版本数量超过设置的最大版本数，按从新到旧的顺序返回指定版本数量的数据。
time_range（可选）	Tuple	数据版本范围。必须设置最大版本数和版本范围的其中一个。表格存储数据表的每个属性列可以有不同的数据版本，设置版本范围后，仅返回版本范围内的数据。
limit（可选）	int	单次返回最大行数，必须大于 0。如果符合查询条件的数据行数大于设置的值，将返回指定的最大行数和用于下一次查询的起始主键值。
columns_to_get（可选）	List[str]	指定读取的数据列，可以是主键列或属性列。不设置columns_to_get时，返回整行数据。设置columns_to_get时，如果读取的行数据不包含任何指定的数据列，将返回 null。
column_filter（可选）	ColumnCondition	过滤条件，详情请参见过滤器。如果同时设置columns_to_get和column_filter，先按columns_to_get筛选符合条件的数据行，再按column_filter条件过滤数据。
transaction_id（可选）	str	局部事务ID，用于唯一标识局部事务，详情请参见局部事务。

示例代码

以下示例代码用于读取 test_table 表中主键值大于 row1 的数据。

try:
    # 设置查询起始主键
    inclusive_start_primary_key = [('id', 'row1')]
    # 设置查询结束主键（返回结果不包含结束主键）
    exclusive_end_primary_key = [('id', INF_MAX)]

    # 调用 get_range 方法查询数据
    consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
                                                                              inclusive_start_primary_key, exclusive_end_primary_key)

    # 返回结果处理
    print('* Read CU Cost: %s' % consumed.read)
    print('* Write CU Cost: %s' % consumed.write)
    print('* Rows Data:')
    for row in row_list:
        print(row.primary_key, row.attribute_columns)
except Exception as e:
    print("Range get failed with error: %s" % e)

单次范围扫描数据上限为 5000 行或者 4 MB，超出限制部分的数据将返回用于下一次读取的起始主键值，您可以参考以下代码进行迭代查询。

while True:
    # 调用 get_range 方法查询数据
    consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
                                                                              inclusive_start_primary_key,
                                                                              exclusive_end_primary_key)

    # 返回结果处理
    print('* Read CU Cost: %s' % consumed.read)
    print('* Write CU Cost: %s' % consumed.write)
    print('* Rows Count: %s' % len(row_list))
    print('* Rows Data:')
    for row in row_list:
        print(row.primary_key, row.attribute_columns)

    # 设置下一次读取数据起始主键
    if next_start_primary_key:
        inclusive_start_primary_key = next_start_primary_key
    else:
        break

您也可以在查询数据时参考示例代码进行以下设置。

设置读取的数据版本范围，结果只返回版本范围内的数据。

# 设置查询的数据版本范围为当前时间往前一天
time_range = (int(time.time() * 1000 - 86400 * 1000), int(time.time() * 1000))

consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
                                                                          inclusive_start_primary_key, exclusive_end_primary_key,
                                                                          time_range= time_range)

指定读取的属性列。

columns_to_get = ['col1']

# 调用 get_range 方法查询数据
consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
                                                                          inclusive_start_primary_key, exclusive_end_primary_key,
                                                                          columns_to_get)

设置单次返回最大行数。

limit = 10

# 调用 get_range 方法查询数据
consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
                                                                          inclusive_start_primary_key, exclusive_end_primary_key,
                                                                          limit=limit)

表格存储：范围读取数据

前提条件

方法说明

示例代码

相关文档