Table Store Python SDK過濾器 - Tablestore

前提條件

使用過濾器前，需完成以下準備：

初始化Tablestore Client

過濾器工作原理

過濾器在服務端掃描完主鍵範圍內的行之後執行。無論某行是否通過過濾條件，掃描該行均會消耗讀取 CU。因此，過濾器適合在已縮小主鍵範圍的基礎上進一步篩選資料，不建議用於過濾大量行以擷取少量結果。

Table Store提供兩種過濾器類型：

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

範例程式碼

相關文檔