全部產品
Search
文件中心

Tablestore:過濾器

更新時間:Jul 24, 2024

在服務端對讀取結果再進行一次過濾,根據過濾器(Filter)中的條件決定返回的行。使用過濾器後,只返回合格資料行。

前提條件

使用方法

在通過GetRow、BatchGetRow或GetRange介面查詢資料時,可以使用過濾器只返回合格資料行。

過濾器目前包括SingleColumnValueFilter和CompositeColumnValueFilter。

  • SingleColumnValueFilter:只判斷某個參考列的列值。

  • CompositeColumnValueFilter:根據多個參考列的列值的判斷結果進行邏輯組合,決定是否過濾某行。

說明

關於過濾器的更多資訊,請參見功能介紹中的過濾器

注意事項

  • 過濾器的條件支援算術運算(=、!=、>、>=、<、<=)和邏輯運算(NOT、AND、OR),最多支援10個條件的組合。

  • 過濾器中的參考列必須在讀取的結果內。如果指定的要讀取的列中不包含參考列,則過濾器無法擷取參考列的值。

  • 在GetRow、BatchGetRow和GetRange介面中使用過濾器不會改變介面的原生語義和限制項。

    使用GetRange介面時,會受到一次掃描資料的行數不能超過5000行或者掃描資料的資料大小不能大於4 MB的限制。

    當在該次掃描的5000行或者4 MB資料中沒有滿足過濾器條件的資料時,得到的Response中的Rows為空白,但是next_start_primary_key可能不為空白,此時需要使用next_start_primary_key繼續讀取資料,直到next_start_primary_key為空白。

參數

過濾器可以用於GetRow、BatchGetRow和GetRange介面的column_filter中。

    'column_filter' => <ColumnFilter>
  • SingleColumnValueFilter結構

    SingleColumnValueFilter支援一列(可以是主鍵列)和一個常量比較。不支援兩列或者兩個常量相比較。

        [
            'column_name' => '<string>',
            'value' => <ColumnValue>,
            'comparator' => <ComparatorType>,
            'pass_if_missing' => true || false,
            'latest_version_only' => true || false
        ]
            
  • CompositeColumnValueFilter結構

    CompositeColumnValueFilter是一個樹形結構,內節點為邏輯運算(logical_operator),分葉節點為SingleColumnValueFilter。

        [
            'logical_operator' => <LogicalOperator>
            'sub_filters' => [
                <ColumnFilter>,
                <ColumnFilter>,
                <ColumnFilter>,
                // other conditions
            ]
        ]
            

參數

說明

column_name

過濾器中參考列的名稱。

value

過濾器中參考列的對比值。

格式為[Value, Type]。Type可以是INTEGER、STRING(UTF-8編碼字串)、BINARY、BOOLEAN、DOUBLE五種,分別用ColumnTypeConst::CONST_INTEGER、ColumnTypeConst::CONST_STRING、ColumnTypeConst::CONST_BINARY、ColumnTypeConst::CONST_BOOLEAN、ColumnTypeConst::CONST_DOUBLE表示,其中BINARY不可省略,其他類型均可省略。

當Type不是BINARY時,可以簡寫為Value。

comparator

過濾器中的算術運算子,類型詳情請參見ComparatorType

算術運算子包括EQUAL(=)、NOT_EQUAL(!=)、GREATER_THAN(>)、GREATER_EQUAL(>=)、LESS_THAN(<)和LESS_EQUAL(<=),分別用ComparatorTypeConst::CONST_EQUAL、ComparatorTypeConst::CONST_NOT_EQUAL、ComparatorTypeConst::CONST_GREATER_THAN、ComparatorTypeConst::CONST_GREATER_EQUAL、ComparatorTypeConst::CONST_LESS_THAN、ComparatorTypeConst::CONST_LESS_EQUAL表示。

logical_operator

過濾器中的邏輯運算子,類型詳情請參見LogicalOperator

邏輯運算子包括NOT、AND和OR,分別用LogicalOperatorConst::CONST_NOT、LogicalOperatorConst::CONST_AND、LogicalOperatorConst::CONST_OR表示。

pass_if_missing

當參考列在某行中不存在時,是否返回該行。類型為bool值,預設值為true,表示如果參考列在某行中不存在,則返回該行。

當pass_if_missing設定為false時,如果參考列在某行中不存在,則不返回該行。

latest_version_only

當參考列存在多個版本的資料時,是否只使用最新版本的值做比較。類型為bool值,預設值為true,表示如果參考列存在多個版本的資料時,則只使用該列最新版本的值進行比較。

當latest_version_only設定為false時,如果參考列存在多個版本的資料時,則會使用該列的所有版本的值進行比較,此時只要有一個版本的值滿足條件,就返回該行。

sub_filters

子節點可以是SingleColumnValueFilter或CompositeColumnValueFilter。

內節點的邏輯運算子不同可以掛載的子節點個數不同。

  • 當內節點的邏輯運算子為NOT時,只能掛載一個子節點。

  • 當內節點的邏輯運算子為AND或OR時,可以掛載多個子節點。

樣本

使用SingleColumnValueFilter過濾資料

以下樣本用於讀取資料表中的一行資料,當col0列值等於0時返回該行資料。

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     //設定讀取最新版本。
    'columns_to_get' => ['col0'],             //設定讀取的列。
    
    //設定過濾器,當Col0的值為0時,返回該行。
    'column_filter' => [
        'column_name' => 'col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL,
        'pass_if_missing' => false,                         //如果不存在Col0列,也不返回該行。
        'latest_version_only' => true                      //只判斷最新版本。
    ]
];
$response = $otsClient->getRow ($request); 

使用CompositeColumnValueFilter過濾資料

以下樣本用於讀取資料表中的一行資料,當Col0列值等於0且Col1小於100時返回該行資料。

    //composite1的條件為(Col0 == 0) AND (Col1 > 100)。
    $composite1 = [
        'logical_operator' => LogicalOperatorConst::CONST_AND,
        'sub_filters' => [
            [
                'column_name' => 'Col0',
                'value' => 0,
                'comparator' => ComparatorTypeConst::CONST_EQUAL
            ],
            [
                'column_name' => 'Col1',
                'value' => 100,
                'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
            ]
        ]
    ];
    //composite2的條件為( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)。
    $composite2 = [
        'logical_operator' => LogicalOperatorConst::CONST_OR,
        'sub_filters' => [
            $composite1,
            [
                'column_name' => 'Col2',
                'value' => 10,
                'comparator' => ComparatorTypeConst::CONST_LESS_EQUAL
            ]
        ]
    ];  
                    

相關文檔

  • 當某些應用需要使用不同屬性作為查詢條件來執行資料查詢時,您可以通過將這些屬性作為二級索引的主鍵列實現按照屬性快速查詢資料的需求。更多資訊,請參見二級索引

  • 當日常業務中有非主鍵列查詢、多列組合查詢、模糊查詢等多維查詢需求以及求最值、統計行數、資料分組等資料分析需求時,您可以將這些屬性作為多元索引中的欄位並使用多元索引查詢與分析資料。 更多資訊,請參見多元索引

  • 您還可以通過SQL查詢與分析表中資料。更多資訊,請參見查詢資料