表格存储 Python SDK过滤器-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

使用过滤器前，需完成以下准备：

初始化Tablestore Client

过滤器工作原理

过滤器在服务端扫描完主键范围内的行之后执行。无论某行是否通过过滤条件，扫描该行均会消耗读取 CU。因此，过滤器适合在已缩小主键范围的基础上进一步筛选数据，不建议用于过滤大量行以获取少量结果。

表格存储提供两种过滤器类型：

SingleColumnCondition：对单个属性列的值进行条件判断。适用于基于某一列值的简单过滤场景。
CompositeColumnCondition：将多个条件通过逻辑运算符（AND、OR、NOT）组合。适用于多列联合过滤或复杂条件判断场景，最多支持 32 个条件组合。

SingleColumnCondition

对单个属性列的值进行关系运算，判断该列是否满足过滤条件。

class SingleColumnCondition(ColumnCondition)

参数说明

名称	类型	说明
comparator（必选）	ComparatorType	关系运算符。取值：`EQUAL`（等于）、`NOT_EQUAL`（不等于）、`GREATER_THAN`（大于）、`GREATER_EQUAL`（大于等于）、`LESS_THAN`（小于）、`LESS_EQUAL`（小于等于）。
column_name（必选）	str	判断的属性列名称。
column_value（必选）	str，int，bytes，float，bool	判断的值。
pass_if_missing（可选）	bool	行数据不包含判断的属性列时，是否返回该行。默认值为 `True`，即返回该行。
latest_version_only（可选）	bool	是否只判断最新版本的数据。默认值为 `True`。设置为 `True` 时，即使该列存在多个版本，也只判断最新版本是否满足条件。

示例代码

以下示例通过范围查询获取主键在 [row1, row3) 范围内的行数据，并过滤出 col1 属性列的值等于 val1 的行。

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

    # 构造过滤器，条件为 col1 == "val1"
    singleColumnCondition = SingleColumnCondition('col1', 'val1', ComparatorType.EQUAL)

    # 调用 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,
                                                                              column_filter=singleColumnCondition)

    # 返回结果处理
    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)

行数据不包含判断的属性列时，不返回该行：
```
singleColumnCondition.pass_if_missing = False
```
判断所有版本的数据，任意版本满足条件即返回该行：
```
singleColumnCondition.latest_version_only = False
```

CompositeColumnCondition

将多个过滤条件通过逻辑运算符组合，支持 SingleColumnCondition 和 CompositeColumnCondition 嵌套，最多支持 32 个条件的组合。

class CompositeColumnCondition(ColumnCondition)

参数说明

名称	类型	说明
combinator（必选）	LogicalOperator	逻辑运算符。取值：`NOT`（非）、`AND`（与）、`OR`（或）。
sub_conditions（必选）	List[ColumnCondition]	参与逻辑运算的过滤器列表。每项可以是 `SingleColumnCondition` 或 `CompositeColumnCondition`。

示例代码

以下示例通过范围查询获取主键在 [row1, row3) 范围内的行数据，并应用如下组合过滤条件：

(col1 == "val1" OR col2 == "val2") AND col3 == "val3"

try:
    # 设置查询起始主键
    inclusive_start_primary_key = [('id', 'row1')]

    # 设置查询结束主键（返回结果不包含结束主键）
    exclusive_end_primary_key = [('id', 'row3')]

    # 构造单属性列值过滤器1，条件为 col1 == "val1"
    singleColumnCondition1 = SingleColumnCondition('col1', 'val1', ComparatorType.EQUAL)
    # 构造单属性列值过滤器2，条件为 col2 == "val2"
    singleColumnCondition2 = SingleColumnCondition('col2', 'val2', ComparatorType.EQUAL)
    # 构造组合过滤器1，条件为 col1 == "val1" OR col2 == "val2"
    compositeColumnCondition1 = CompositeColumnCondition(LogicalOperator.OR)
    compositeColumnCondition1.add_sub_condition(singleColumnCondition1)
    compositeColumnCondition1.add_sub_condition(singleColumnCondition2)
    # 构造单属性列值过滤器3，条件为 col3 == "val3"
    singleColumnCondition3 = SingleColumnCondition('col3', 'val3', ComparatorType.EQUAL)
    # 构造组合过滤器2，条件为 (col1 == "val1" OR col2 == "val2") AND col3 == "val3"
    compositeColumnCondition2 = CompositeColumnCondition(LogicalOperator.AND)
    compositeColumnCondition2.add_sub_condition(compositeColumnCondition1)
    compositeColumnCondition2.add_sub_condition(singleColumnCondition3)

    # 调用 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,
                                                                              column_filter=compositeColumnCondition2)

    # 返回结果处理
    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)

前提条件

过滤器工作原理

SingleColumnCondition

示例代码

CompositeColumnCondition

示例代码

相关文档