在服務端對讀取結果再進行一次過濾，根據過濾器（Filter）中的條件決定返回的行。使用過濾器後，只返回合格資料行，從而有效降低網路傳輸的資料量，減少回應時間。

情境

  • 直接過濾結果

    以物聯網中的智能電錶為例，智能電錶按一定的頻率（例如每隔15秒）將當前的電壓、電流、度數等資訊寫入Tablestore。在按天做分析時，需要擷取某一個電錶當天是否出現過電壓異常以及出現時的其他狀態資料，用於判斷是否需要對某條線路進行檢修。

    按照目前的方案，使用GetRange讀取一個電錶一天內的所有的監控資料，共有5760條，然後再對5760條資訊進行過濾，最終擷取了10個電壓出現不穩定時的監控資訊。

    使用過濾器只返回了實際需要的10條資料，有效降低了返回的資料量。而且無需再對結果進行初步的過濾處理，節省了開發成本。

  • 正則匹配並轉換資料類型後再過濾結果

    當某些列中儲存了自訂格式資料（例如JSON格式字串）時，如果使用者希望過濾查詢該列的某個子欄位值，則可以通過Regex匹配並轉換子欄位實值型別後，再使用過濾器來過濾需要的資料。

    例如列中儲存的資料為{cluster_name:name1,lastupdatetime:12345}格式，如果需要過濾查詢lastupdatetime>12345的行資料，此時您可以通過Regexlastupdatetime:([0-9]+)}來匹配該列中子欄位的資料，然後將匹配結果使用CAST轉換為數實值型別，再進行數實值型別的比較，從而過濾得到所需要的資料行。

限制

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

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

介面

過濾器可以用於GetRow、BatchGetRow和GetRange。在GetRow、BatchGetRow和GetRange介面中使用過濾器不會改變介面的原生語義和限制項，具體操作，請參見寫入資料和讀取資料。

過濾器目前包括SingleColumnValueFilter、SingleColumnValueRegexFilter和CompositeColumnValueFilter，是基於一個或者多個參考列的列值決定是否過濾某行。

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

    當參考列不存在時，可以使用PassIfMissing參數決定此時是否滿足條件，即設定當參考列不存在時的行為。

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

使用

您可以使用如下語言的SDK實現過濾器功能。

參數

參數說明
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時，如果參考列存在多個版本的資料時，則會使用該列的所有版本的值進行比較，此時只要有一個版本的值滿足條件，就返回該行。

RegexRegex，用於匹配子欄位值。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]+),", RegexRule.CastType.VT_INTEGER);
 //設定過濾器，實現cast<int>(regex(col1)) > 0。
 //構造SingleColumnValueRegexFilter，格式為“列名,正則規則,比較符,比較值”。
 SingleColumnValueRegexFilter filter =  new SingleColumnValueRegexFilter("Col1",
     regexRule,SingleColumnValueRegexFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(0));
  • 構造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);

計費

使用過濾器功能不影響現有計費規則。

使用過濾器後，可以有效降低返回的資料量，但是由於過濾計算是伺服器端在返回資料前進行的，並未降低磁碟IO次數，所以消耗的讀CU與不使用過濾器時相同。例如使用GetRange讀取到100條記錄，共200 KB資料，消耗了50單位讀CU，在使用過濾器後，實際只返回了10條資料，共20 KB，但是仍然會消耗50單位讀CU。