Java SDK使用過濾器返回符合條件資料行 - Tablestore

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

前提條件

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

使用方法

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

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

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

說明

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

注意事項

過濾器的條件支援關係運算（=、!=、>、>=、<、<=）和邏輯運算（NOT、AND、OR），最多支援10個條件的組合。
過濾器中的參考列必須在讀取的結果內。如果指定的要讀取的列中不包含參考列，則過濾器無法擷取參考列的值。
使用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	當參考列存在多個版本的資料時，是否只使用最新版本的值做比較。取值範圍如下： true（預設）：如果參考列存在多個版本的資料時，則只使用該列最新版本的值進行比較。 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列的值過濾資料。

private static void getRow(SyncClient client, String pkValue) {
    //構造主鍵。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();

    //讀取一行資料，設定資料表名稱。
    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria("<TABLE_NAME>", primaryKey);
    //設定讀取最新版本。
    criteria.setMaxVersions(1);

    //設定過濾器，當Col0列的值為0時，返回該行。
    SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
            SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
    //如果Col0列不存在，則不返回該行。
    singleColumnValueFilter.setPassIfMissing(false);
    criteria.setFilter(singleColumnValueFilter);

    GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
    Row row = getRowResponse.getRow();

    System.out.println("讀取完畢，結果為: ");
    System.out.println(row);
}

使用SingleColumnValueRegexFilter正則過濾數

以下樣本用於讀取主鍵範圍為["pk:2020-01-01.log", "pk:2021-01-01.log")時Col1列的資料，並對該列的資料執行正則過濾。

private static void getRange(SyncClient client) {
    //設定資料表名稱。
    RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("<TABLE_NAME>");
 
    //設定主鍵範圍為["pk:2020-01-01.log", "pk:2021-01-01.log")，讀取範圍為左閉右開的區間。
    PrimaryKey pk0 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("2020-01-01.log"))
        .build();
    PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("2021-01-01.log"))
        .build();
    criteria.setInclusiveStartPrimaryKey(pk0);
    criteria.setExclusiveEndPrimaryKey(pk1);
 
    //設定讀取最新版本。
    criteria.setMaxVersions(1);
 
    //設定過濾器，當cast<int>(regex(Col1)) > 100時，返回該行。
    RegexRule regexRule = new RegexRule("t1:([0-9]+),", RegexRule.CastType.VT_INTEGER);
    SingleColumnValueRegexFilter filter =  new SingleColumnValueRegexFilter("Col1",
        regexRule,SingleColumnValueRegexFilter.CompareOperator.GREATER_THAN,ColumnValue.fromLong(100));
    criteria.setFilter(filter);

    while (true) {
        GetRangeResponse resp = client.getRange(new GetRangeRequest(criteria));
        for (Row row : resp.getRows()) {
            // do something
            System.out.println(row);
        }
        if (resp.getNextStartPrimaryKey() != null) {
            criteria.setInclusiveStartPrimaryKey(resp.getNextStartPrimaryKey());
        } else {
            break;
        }
   }
}

使用CompositeColumnValueFilter過濾資料

以下樣本用於返回主鍵範圍在["a","h")之間，Col0列值等於0且Col1列值大於100或者Col2列值小於等於10的行。

private static void getRange(SyncClient client) {
    //設定資料表名稱。
    RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("<TABLE_NAME>");

    //設定主鍵範圍，讀取範圍為左閉右開的區間。
    PrimaryKey pk0 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("a"))
            .build();
    PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("h"))
            .build();
    criteria.setInclusiveStartPrimaryKey(pk0);
    criteria.setExclusiveEndPrimaryKey(pk1);

    //設定讀取最新版本。
    criteria.setMaxVersions(1);

    //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);
    criteria.setFilter(composite2);

    while (true) {
        GetRangeResponse resp = client.getRange(new GetRangeRequest(criteria));
        for (Row row : resp.getRows()) {
            // do something
            System.out.println(row);
        }
        if (resp.getNextStartPrimaryKey() != null) {
            criteria.setInclusiveStartPrimaryKey(resp.getNextStartPrimaryKey());
        } else {
            break;
        }
    }
}

Tablestore：過濾器