在服務端對讀取結果再進行一次過濾，根據過濾器（Filter）中的條件決定返回的行。使用過濾器后，只返回符合條件的數據行。
前提條件
已初始化Client。具體操作，請參見初始化OTSClient。
使用方法
在通過GetRow、BatchGetRow或GetRange接口查詢數據時，可以使用過濾器只返回符合條件的數據行。
過濾器目前包括SingleColumnValueFilter、SingleColumnValueRegexFilter和CompositeColumnValueFilter。
SingleColumnValueFilter：只判斷某個參考列的列值。
SingleColumnValueRegexFilter：支持對類型為String的列值，使用正則表達式進行子字符串匹配，然后根據實際將匹配到的子字符串轉換為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 | 當參考列在某行中不存在時，是否返回該行。取值范圍如下：
|
LatestVersionsOnly | 當參考列存在多個版本的數據時，是否只使用最新版本的值做比較。取值范圍如下：
|
Regex | 正則表達式，用于匹配子字段值。正則表達式必須滿足以下條件：
|
VariantType | 使用正則表達式匹配到子字段值后，子字段值轉換為的類型。取值范圍為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;
}
}
}