フィルターの使用 - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

Tablestore SDK for Python を使用して、サーバー側で属性列の値に基づいて行をフィルタリングし、クライアントに返されるデータ量を削減します。

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化します。

機能の説明

フィルターは、サーバーがデータを読み取った後に適用されます。条件を満たす行のみがクライアントに返されます。フィルタリングでは、サーバーが読み取る行数や消費される読み込み CU は削減されません。プライマリキーの範囲を絞り込んだ後にフィルターを使用することを推奨します。

以下のフィルター条件がサポートされています。

SingleColumnCondition ：1 つの属性列の値を比較します。
SingleColumnRegexCondition ：文字列属性列から部分文字列を抽出し、抽出した値を比較します。
CompositeColumnCondition ：最大 32 個の条件を AND、OR、または NOT で組み合わせます。

次の例では、範囲の読み取り中に、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 互換の表現と 1 バイト文字がサポートされています。中国語の文字はサポートされていません。表現にキャプチャグループが含まれている場合、最初のグループが抽出されます。それ以外の場合は、一致全体が抽出されます。
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 に設定します。status 属性列のいずれかのバージョンが online であれば、行が返されます。status 列がない行は返されません。

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