過濾器 - Tablestore

前提條件

已初始化Client。具體操作，請參見初始化。
已建立資料表並寫入資料。

使用方法

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

過濾器目前包括SingleColumnValueFilter、SingleColumnValueRegexFilter和CompositeColumnValueFilter。

SingleColumnValueFilter：只判斷某個參考列的列值。
SingleColumnValueRegexFilter：支援對類型為String的列值，使用Regex進行子字串匹配，然後根據實際將匹配到的子字串轉換為String、Integer或者Double類型，再對子值使用過濾器進行過濾。
CompositeColumnValueFilter：根據多個參考列的列值的判斷結果進行邏輯組合，決定是否過濾某行。

说明關於過濾器的更多資訊，請參見功能介紹中的過濾器。

限制

過濾器的條件支援關係運算（=、!=、>、>=、<、<=）和邏輯運算（NOT、AND、OR），最多支援10個條件的組合。
過濾器中的參考列必須在讀取的結果內。如果指定的要讀取的列中不包含參考列，則過濾器無法擷取參考列的值。
在GetRow、BatchGetRow和GetRange介面中使用過濾器不會改變介面的原生語義和限制項。
使用GetRange介面時，一次掃描資料的行數不能超過5000行或者資料大小不能超過4 MB。

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

參數


參數	說明
ColumnName	過濾器中參考列的名稱。
ColumnValue	過濾器中參考列的對比值。
CompareOperator	過濾器中的關係運算子。關係運算子包括EQUAL（=）、NOT_EQUAL（!=）、GREATER_THAN（>）、GREATER_EQUAL（>=）、LESS_THAN（<）和LESS_EQUAL（<=）。
LogicOperator	過濾器中的邏輯運算子。邏輯運算子包括NOT、AND和OR。
PassIfMissing	當參考列在某行中不存在時，是否返回該行。取值範圍如下： true（預設）：如果參考列在某行中不存在時，則返回該行。 false：如果參考列在某行中不存在時，則不返回該行。
LatestVersionsOnly	當參考列存在多個版本的資料時，是否只使用最新版本的值做比較。類型為bool值，預設值為true，表示如果參考列存在多個版本的資料時，則只使用該列最新版本的值進行比較。當設定LatestVersionsOnly為false時，如果參考列存在多個版本的資料時，則會使用該列的所有版本的值進行比較，此時只要有一個版本的值滿足條件，就返回該行。
Regex	Regex，用於匹配子欄位值。Regex必須滿足以下條件：長度不能超過256個位元組。支援perl regular文法。支援單位元組Regex。不支援中文的正則匹配。支援Regex的全匹配模式和部分匹配模式。部分匹配的Regex在模式中由一對括弧（…）分隔。如果Regex為全匹配模式，則返回第一個匹配結果；如果Regex中包含部分匹配文法，則返回第一個滿足的子匹配結果。例如列值為1aaa51bbb5，如果Regex為1[a-z]+5時，則傳回值為1aaa5；如果Regex為1([a-z]+)5，則傳回值為aaa。
VariantType	使用Regex匹配到子欄位值後，子欄位值轉換為的類型。取值範圍為VT_INTEGER（整型）、VT_STRING（字串類型）和VT_DOUBLE（雙精確度浮點型）。

樣本

構造SingleColumnValueFilter。

  //設定過濾器，當Col0列的值為0時，返回該行。
  SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
          SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
  //如果不存在Col0列，也不返回該行。
  singleColumnValueFilter.setPassIfMissing(false);
  //只使用該列最新版本的值進行比較。
  singleColumnValueFilter.setLatestVersionsOnly(true);

構造SingleColumnValueRegexFilter。

 //構造正則抽取規則。
 RegexRule regexRule = new RegexRule("t1:([0-9]+),", VariantType.Type.VT_INTEGER);
 //設定過濾器，實現cast<int>(regex(col1)) > 0。
 //構造SingleColumnValueRegexFilter，格式為“列名,正則規則,比較符,比較值”。
 SingleColumnValueRegexFilter filter =  new SingleColumnValueRegexFilter("Col1",
     regexRule,SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(0));
 //如果不存在Col0列，也不返回該行。
 filter.setPassIfMissing(false);

構造CompositeColumnValueFilter。

  //composite1的條件為(Col0 == 0) AND (Col1 > 100)。
  CompositeColumnValueFilter composite1 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.AND);
  SingleColumnValueFilter single1 = new SingleColumnValueFilter("Col0",
          SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
  SingleColumnValueFilter single2 = new SingleColumnValueFilter("Col1",
          SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100));
  composite1.addFilter(single1);
  composite1.addFilter(single2);

  //composite2的條件為( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)。
  CompositeColumnValueFilter composite2 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.OR);
  SingleColumnValueFilter single3 = new SingleColumnValueFilter("Col2",
          SingleColumnValueFilter.CompareOperator.LESS_EQUAL, ColumnValue.fromLong(10));
  composite2.addFilter(composite1);
  composite2.addFilter(single3);