表格存储 Java SDK 过滤器-表格存储 Tablestore(Tablestore)-阿里云帮助中心

Java SDK 在服务端按条件筛选属性列值，减少返回客户端的数据量，降低网络传输开销。支持单列值过滤、正则过滤和组合过滤三种类型。

前提条件

安装 Tablestore Java SDK并初始化客户端。

功能说明

过滤器在服务端读取数据后执行筛选，只将符合条件的行返回给客户端。筛选发生在数据读取之后，不影响实际读取的行数，但可减少网络传输的数据量。

通过查询请求（SingleRowQueryCriteria / RangeRowQueryCriteria / MultiRowQueryCriteria / RangeIteratorParameter）的 setFilter 方法附加过滤器实例。表格存储 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`：正则表达式，用于匹配子字符串，长度不超过 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);