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

前提条件

安装Tablestore Java SDK并初始化客户端。
使用 5.17.5 及以上版本的 Tablestore Java SDK。

功能说明

查询后过滤（SearchFilter）在主查询（query）完成后对候选数据进行二次筛选，筛选结果再参与统计聚合和分组。将适合后置执行的条件配置为查询后过滤条件，可减少复杂条件在主查询阶段的计算开销；是否能改善性能取决于主查询筛选效果和过滤条件。

调用 search 方法时，在 SearchQuery 中分别设置主查询条件和 SearchFilter。主查询可使用多元索引支持的查询类型；查询后过滤条件仅支持特定查询类型和字段，具体限制请参见使用限制。

SearchResponse search(SearchRequest request)

以下示例先通过 TermsQuery 查询 category 字段值为 book 的数据，再通过查询后过滤保留 score_long 字段值大于 1 且小于 10 的数据。

String tableName = "example_table";
String indexName = "example_index";

// 设置主查询条件。
TermsQuery termsQuery = new TermsQuery();
termsQuery.setFieldName("category");
termsQuery.addTerm(ColumnValue.fromString("book"));

// 设置查询后过滤条件。
RangeQuery rangeQuery = new RangeQuery();
rangeQuery.setFieldName("score_long");
rangeQuery.setFrom(ColumnValue.fromLong(1));
rangeQuery.setIncludeLower(false);
rangeQuery.setTo(ColumnValue.fromLong(10));
rangeQuery.setIncludeUpper(false);

SearchFilter searchFilter = new SearchFilter();
searchFilter.setQuery(rangeQuery);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(termsQuery);
searchQuery.setFilter(searchFilter);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet =
        new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAllFromIndex(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
System.out.println("Total count: " + response.getTotalCount());
System.out.println("Rows: " + response.getRows());

使用限制

查询后过滤必须与主查询条件组合使用。为减少进入查询后过滤阶段的数据量，应通过主查询尽可能缩小候选数据范围；除非需要对全部索引数据执行过滤，否则不建议将主查询设置为 MatchAllQuery。
过滤条件仅支持 TermQuery、TermsQuery、RangeQuery、ExistsQuery，以及由这些查询类型组成的 BoolQuery。
过滤条件中的 BoolQuery 仅支持 mustQueries、mustNotQueries 和 shouldQueries，不支持 filterQueries。
过滤字段仅支持 Keyword、Long 和 Double 类型，并且必须启用 enableSortAndAgg。
过滤条件不参与相关性评分。为过滤条件设置 weight 不会改变查询结果的相关性得分。

参数说明

查询请求

request 的类型为 SearchRequest，包含以下参数。

名称	类型	说明
tableName（必选）	String	数据表名称。
indexName（必选）	String	多元索引名称。
searchQuery（必选）	SearchQuery	主查询条件、查询后过滤条件和通用查询配置。
columnsToGet（可选）	SearchRequest.ColumnsToGet	返回列配置。未设置时只返回主键列。
timeoutInMillisecond（可选）	int	请求级查询超时时间，单位为毫秒。默认值为 `-1`，表示不单独设置查询超时时间。
routingValues（可选）	`List<PrimaryKey>`	自定义路由字段对应的主键值列表。未配置自定义路由时无需设置。

查询配置

request.searchQuery 的类型为 SearchQuery，包含以下参数。

名称	类型	说明
query（必选）	Query	主查询条件。支持多元索引的查询类型。
filter（必选）	SearchFilter	查询后过滤配置，在主查询完成后进一步筛选候选数据。
offset（可选）	Integer	本次查询的起始位置。
limit（可选）	Integer	本次查询返回的最大行数。设置为 `0` 时不返回具体行。
highlight（可选）	Highlight	`Text` 字段的摘要与高亮配置。有关配置方法，请参见摘要与高亮。
collapse（可选）	Collapse	结果折叠配置，用于按指定列对返回结果去重。有关配置方法，请参见折叠（去重）。
sort（可选）	Sort	返回结果的排序方式。有关配置方法，请参见排序和翻页。
trackTotalCount（可选）	int	期望统计的最大匹配行数。默认值为 `TRACK_TOTAL_COUNT_DISABLED`，表示不统计；设置为 `TRACK_TOTAL_COUNT` 时统计全部匹配行。值越小，查询性能越高。
aggregationList（可选）	`List<Aggregation>`	统计聚合配置。统计聚合基于查询后过滤结果执行。有关配置方法，请参见统计聚合。
groupByList（可选）	`List<GroupBy>`	分组配置。分组基于查询后过滤结果执行。有关配置方法，请参见统计聚合。
token（可选）	byte[]	翻页凭证。将上一次响应的 `nextToken` 设置为该参数可继续读取后续数据。设置 `token` 时，SDK 会清除 `sort`，因为翻页凭证中已包含排序条件。

查询后过滤配置

request.searchQuery.filter 的类型为 SearchFilter，包含以下参数。

名称	类型	说明
query（必选）	Query	过滤条件。仅支持 `TermQuery`、`TermsQuery`、`RangeQuery`、`ExistsQuery`，以及由这些查询类型组成的 `BoolQuery`。

返回列

request.columnsToGet 的类型为 SearchRequest.ColumnsToGet，包含以下参数。

名称	类型	说明
columns（可选）	`List<String>`	要返回的属性列名称。仅 `returnAll` 和 `returnAllFromIndex` 均为 `false` 时需要设置；未设置时只返回主键列。
returnAll（可选）	boolean	是否返回数据表中的全部属性列。默认值为 `false`。
returnAllFromIndex（可选）	boolean	是否返回已建立索引的全部属性列。默认值为 `false`。不能与 `returnAll` 同时设置为 `true`。

返回值

search 方法返回 SearchResponse。核心字段如下。

名称	类型	说明
totalCount	long	查询后过滤后的匹配行数，通过 `getTotalCount()` 获取。返回值取决于 `trackTotalCount` 配置。
rows	`List<Row>`	本次查询返回的行数据，通过 `getRows()` 获取。返回数量不超过 `limit`。
searchHits	`List<SearchHit>`	查询命中结果，通过 `getSearchHits()` 获取。
aggregationResults	AggregationResults	基于查询后过滤结果计算的统计聚合结果，通过 `getAggregationResults()` 获取。
groupByResults	GroupByResults	基于查询后过滤结果计算的分组结果，通过 `getGroupByResults()` 获取。
nextToken	byte[]	下一页凭证，通过 `getNextToken()` 获取。值不为 `null` 时，将其设置到下一次请求的 `token` 中继续读取。
isAllSuccess	boolean	是否已成功查询全部索引分区，通过 `isAllSuccess()` 获取。值为 `false` 时，返回的是部分结果，`totalCount` 可能小于实际匹配行数。