Table Store Python SDK 過濾器 - Tablestore

使用 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`	Regex，長度不超過 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,
)