Table Store Java SDK 過濾器 - Tablestore

Java SDK 在服務端按條件式篩選屬性列值，減少返回用戶端的資料量，降低網路傳輸開銷。支援單列值過濾、正則過濾和組合過濾三種類型。

前提條件

安裝 Tablestore Java SDK並初始化用戶端。

功能說明

過濾器在服務端讀取資料後執行篩選，只將合格行返回給用戶端。篩選發生在資料讀取之後，不影響實際讀取的行數，但可減少網路傳輸的資料量。

通過查詢請求（SingleRowQueryCriteria / RangeRowQueryCriteria / MultiRowQueryCriteria / RangeIteratorParameter）的 setFilter 方法附加過濾器執行個體。Table Store Java SDK 提供以下三種過濾器：

SingleColumnValueFilter：單屬性列值過濾器。判斷單個屬性列的值是否符合關係運算條件。
SingleColumnValueRegexFilter：單屬性列正則過濾器。對 String 類型的屬性列按正則提取子字串後轉換資料類型，再按關係運算判斷。
CompositeColumnValueFilter：組合過濾器。用邏輯運算子（AND / OR / NOT）組合多個過濾器，最多支援 32 個條件。

以下樣本從資料表 filter_demo 中讀取 col1 等於 val1 的行，使用最常用的 SingleColumnValueFilter。

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

PrimaryKeyBuilder startBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startBuilder.build());

PrimaryKeyBuilder endBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endBuilder.build());

criteria.setMaxVersions(1);

// 構造過濾器：col1 == "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Matched rows: " + response.getRows().size());

參數說明

SingleColumnValueFilter

public class SingleColumnValueFilter extends ColumnValueFilter

呼叫簽章：new SingleColumnValueFilter(columnName, operator, columnValue)。

名稱	類型	說明
columnName（必選）	String	待判斷的屬性列名稱。
operator（必選）	CompareOperator	關係運算子，取值包括： `EQUAL`（等於） `NOT_EQUAL`（不等於） `GREATER_THAN`（大於） `GREATER_EQUAL`（大於等於） `LESS_THAN`（小於） `LESS_EQUAL`（小於等於）
columnValue（必選）	ColumnValue	比較判斷的值。
passIfMissing（可選）	boolean	行不包含判斷的屬性列時，是否返回該行。預設 `true`（包含則返回）。設定為 `false` 時，不包含該屬性列的行不會返回。
latestVersionsOnly（可選）	boolean	是否只判斷最新的資料版本。預設 `true`（只判斷最新版本）。設定為 `false` 時，任意版本符合條件即返回該行。

SingleColumnValueRegexFilter

public class SingleColumnValueRegexFilter extends ColumnValueFilter

呼叫簽章：new SingleColumnValueRegexFilter(columnName, regexRule, operator, columnValue)。只有 String 類型的屬性列支援正則過濾。

名稱	類型	說明
columnName（必選）	String	待判斷的屬性列名稱（必須為 String 類型）。
regexRule（必選）	RegexRule	正則匹配規則，包含 `regex` 和 `castType` 兩個參數。 `regex`：Regex，用於匹配子字串，長度不超過 256 位元組。支援 Perl 正則和單位元組正則；不支援中文匹配；支援分組文法（含分組時返回第一個匹配的子字串，例如待匹配列值 `1aaa51bbb5`、正則 `1([a-z]+)5`，返回 `aaa`）。 `castType`：子字串轉換的類型，取值 `VT_INTEGER`（整型）、`VT_DOUBLE`（雙精確度浮點型）、`VT_STRING`（字串）。
operator（必選）	CompareOperator	關係運算子，取值同 `SingleColumnValueFilter`（`EQUAL` / `NOT_EQUAL` / `GREATER_THAN` / `GREATER_EQUAL` / `LESS_THAN` / `LESS_EQUAL`）。
columnValue（必選）	ColumnValue	比較判斷的值，類型應與 `castType` 一致。

CompositeColumnValueFilter

public class CompositeColumnValueFilter extends ColumnValueFilter

呼叫簽章：new CompositeColumnValueFilter(logicOperator)，再通過 addFilter() 添加各子過濾器。最多支援 32 個條件。

名稱

類型

說明

type（必選）

LogicOperator

邏輯運算子，取值包括：

AND（與）
OR（或）
NOT（非）

filters（必選）

List<ColumnValueFilter>

參與邏輯運算的子過濾器，通過 addFilter() 添加。可以是 SingleColumnValueFilter、SingleColumnValueRegexFilter 或 CompositeColumnValueFilter（支援嵌套）。

情境樣本

正則過濾

通過 RegexRule 提取列值中的子字串後再比較。以下樣本對 col2 應用正則 1([a-z]+)5 提取第一個捕獲分組，按字串與 aaa 比較。

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

PrimaryKeyBuilder startBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startBuilder.build());

PrimaryKeyBuilder endBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endBuilder.build());

criteria.setMaxVersions(1);

// 正則 "1([a-z]+)5" 提取第一個捕獲分組；castType=VT_STRING 按字串比較
RegexRule regexRule = new RegexRule("1([a-z]+)5", RegexRule.CastType.VT_STRING);
SingleColumnValueRegexFilter filter = new SingleColumnValueRegexFilter(
        "col2",
        regexRule,
        SingleColumnValueRegexFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("aaa"));
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Matched rows: " + response.getRows().size());

組合過濾

通過 CompositeColumnValueFilter 用邏輯運算子組合多個過濾器，支援嵌套。以下樣本構造條件 (col1 == "val1" OR cast<String>(reg(col2)) >= "aaa") AND col3 == "val3"。

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

PrimaryKeyBuilder startBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startBuilder.build());

PrimaryKeyBuilder endBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endBuilder.build());

criteria.setMaxVersions(1);

// 葉子 1：col1 == "val1"
SingleColumnValueFilter leaf1 = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));

// 葉子 2：cast<String>(reg(col2)) >= "aaa"
RegexRule regexRule = new RegexRule("1([a-z]+)5", RegexRule.CastType.VT_STRING);
SingleColumnValueRegexFilter leaf2 = new SingleColumnValueRegexFilter(
        "col2",
        regexRule,
        SingleColumnValueRegexFilter.CompareOperator.GREATER_EQUAL,
        ColumnValue.fromString("aaa"));

// OR 組合：leaf1 OR leaf2
CompositeColumnValueFilter orFilter = new CompositeColumnValueFilter(
        CompositeColumnValueFilter.LogicOperator.OR);
orFilter.addFilter(leaf1);
orFilter.addFilter(leaf2);

// 葉子 3：col3 == "val3"
SingleColumnValueFilter leaf3 = new SingleColumnValueFilter(
        "col3",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val3"));

// AND 組合：(leaf1 OR leaf2) AND leaf3
CompositeColumnValueFilter andFilter = new CompositeColumnValueFilter(
        CompositeColumnValueFilter.LogicOperator.AND);
andFilter.addFilter(orFilter);
andFilter.addFilter(leaf3);

criteria.setFilter(andFilter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Matched rows: " + response.getRows().size());

進階選項

通過 setPassIfMissing 控制行不包含目標列時的返回行為；通過 setLatestVersionsOnly 控制是否判斷歷史版本資料。

SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));

// 行不包含 col1 時不返回（預設 true：包含則返回）
filter.setPassIfMissing(false);
// 判斷所有版本，任一版本匹配即返回（預設 true：僅判斷最新版本）
filter.setLatestVersionsOnly(false);

criteria.setFilter(filter);