表格存储 Python SDK 过滤器 - 表格存储

使用 Python SDK 在服务端按属性列值筛选行数据，减少返回客户端的数据量。

前提条件

功能说明

过滤器在服务端读取数据后执行，只将符合条件的行返回客户端。过滤不会减少服务端实际读取的行数和消耗的读 CU，适合在已缩小主键范围的基础上进一步筛选数据。

支持以下过滤条件：

SingleColumnCondition：比较单个属性列的值。
SingleColumnRegexCondition：从字符串属性列中提取子字符串后进行比较。
CompositeColumnCondition：使用 AND、OR 或 NOT 组合多个过滤条件，最多支持 32 个条件。

以下示例在范围读取时，只返回 status 属性列的最新值为 online 的行。

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)
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,
    column_filter=column_filter,
)

参数说明

单列值过滤条件

调用 SingleColumnCondition(column_name, column_value, comparator, pass_if_missing=True, latest_version_only=True) 创建单列值过滤条件。

名称	类型	说明
column_name（必选）	`str`	待判断的属性列名称。
column_value（必选）	`str`、`int`、`bytes`、`float`、`bool`	用于比较的目标值。类型必须与属性列值一致。
comparator（必选）	`ComparatorType`	比较运算符。取值为 `EQUAL`、`NOT_EQUAL`、`GREATER_THAN`、`GREATER_EQUAL`、`LESS_THAN` 或 `LESS_EQUAL`。
pass_if_missing（可选）	`bool`	行中不存在目标属性列时是否通过过滤，默认值为 `True`。设置为 `False` 时，不返回缺少该列的行。
latest_version_only（可选）	`bool`	是否只判断属性列的最新版本，默认值为 `True`。设置为 `False` 时，任一版本符合条件即通过过滤。

正则过滤条件

调用 SingleColumnRegexCondition(column_name, comparator, column_value=None, regex_rule=None, latest_version_only=True) 创建正则过滤条件。只有字符串类型的属性列支持正则过滤。

名称	类型	说明
column_name（必选）	`str`	待判断的字符串属性列名称。
comparator（必选）	`ComparatorType`	比较运算符。支持 `EQUAL`、`NOT_EQUAL`、`GREATER_THAN`、`GREATER_EQUAL`、`LESS_THAN`、`LESS_EQUAL`、`EXIST` 和 `NOT_EXIST`。
column_value（可选）	`str`、`int`、`float`	用于比较的目标值。`comparator` 为 `EXIST` 或 `NOT_EXIST` 时必须不设置，其他情况下必须设置。类型需与 `regex_rule.cast_type` 一致。
regex_rule（可选）	`RegexRule`	正则提取和类型转换规则。
latest_version_only（可选）	`bool`	是否只判断属性列的最新版本，默认值为 `True`。设置为 `False` 时，任一版本符合条件即通过过滤。

正则过滤中，行不包含目标属性列时始终不通过过滤，无法单独配置 pass_if_missing。

正则规则

regex_rule 的类型为 RegexRule，包含以下参数。

名称	类型	说明
regex_input（必选）	`str`	正则表达式，长度不超过 256 字节。支持 Perl 正则和单字节字符，不支持匹配中文。包含捕获分组时提取第一个分组；不包含分组时提取整个匹配结果。
cast_type（必选）	`CastType`	提取结果的转换类型。取值为 `VT_STRING`、`VT_INTEGER` 或 `VT_DOUBLE`。转换失败的行不通过过滤。

组合过滤条件

调用 CompositeColumnCondition(combinator) 创建组合过滤条件，再调用 add_sub_condition 添加子条件。

名称	类型	说明
combinator（必选）	`LogicalOperator`	逻辑运算符。取值为 `AND`、`OR` 或 `NOT`。
sub_conditions（必选）	`List[ColumnCondition]`	参与逻辑运算的子条件。支持单列值条件、正则条件和嵌套组合条件，最多组合 32 个条件。

场景示例

正则过滤

以下示例从 account 属性列的 user_004 等值中提取数字，将其转换为整数，并只返回提取结果大于 3 的行。

regex_rule = RegexRule(r"user_(\d+)", CastType.VT_INTEGER)
column_filter = SingleColumnRegexCondition(
    "account",
    ComparatorType.GREATER_THAN,
    3,
    regex_rule,
)

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

组合过滤

以下示例构造 (category == "sensor" OR category == "gateway") AND score > 3 过滤条件。

category_filter = CompositeColumnCondition(LogicalOperator.OR)
category_filter.add_sub_condition(
    SingleColumnCondition("category", "sensor", ComparatorType.EQUAL)
)
category_filter.add_sub_condition(
    SingleColumnCondition("category", "gateway", ComparatorType.EQUAL)
)

column_filter = CompositeColumnCondition(LogicalOperator.AND)
column_filter.add_sub_condition(category_filter)
column_filter.add_sub_condition(
    SingleColumnCondition("score", 3, ComparatorType.GREATER_THAN)
)

判断历史版本

以下示例将 latest_version_only 设置为 False，任一数据版本的值为 online 时即返回该行；缺少 status 属性列的行不返回。

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
    latest_version_only=False,
)