表格存储 Java SDK 多条件组合查询 - 表格存储

前提条件

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

功能说明

多条件组合查询使用 BoolQuery 将一个或多个子查询组合成复杂查询条件。子查询可以是任意 Query 类型，也可以是另一个 BoolQuery。

BoolQuery 支持以下组合方式：

mustQueries：数据必须满足所有子查询，匹配的子查询参与相关性算分，相当于 AND。
filterQueries：数据必须满足所有子查询，但匹配的子查询不参与相关性算分，也相当于 AND。
shouldQueries：数据必须满足不低于 minShouldMatch 指定数量的子查询。满足的子查询越多，相关性得分越高，相当于 OR。
mustNotQueries：数据不能满足其中任何一个子查询，相当于 NOT，且不参与相关性算分。

未设置 minShouldMatch 时，如果同级只包含 shouldQueries 和 mustNotQueries，则默认至少满足一个 shouldQueries 子查询；如果同级包含 mustQueries 或 filterQueries，则 shouldQueries 默认不作为必须满足的条件。

调用 search 方法执行多条件组合查询。

SearchResponse search(SearchRequest request)

以下示例查询 city 等于 hangzhou 且 category 等于 book 的数据，返回最多 10 行数据及匹配总行数。

String tableName = "example_table";
String indexName = "example_index";
TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(Arrays.asList(cityQuery, categoryQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

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

SearchResponse response = client.search(request);
System.out.println(response.getRows());

参数说明

查询请求

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

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

查询配置

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

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

组合查询条件

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

名称	类型	说明
mustQueries（可选）	`List<Query>`	必须全部满足的子查询列表。匹配的子查询参与相关性算分，相当于 AND。
filterQueries（可选）	`List<Query>`	必须全部满足的子查询列表。匹配的子查询不参与相关性算分，相当于 AND。
shouldQueries（可选）	`List<Query>`	至少满足指定数量的子查询列表，相当于 OR。满足的子查询越多，相关性得分越高。
mustNotQueries（可选）	`List<Query>`	不能满足其中任何一个条件的子查询列表，相当于 NOT，且不参与相关性算分。
minShouldMatch（可选）	String 或 int	必须满足的 `shouldQueries` 子查询最小数量。可设置整数，例如 `2`，也可设置百分比字符串，例如 `"75%"`。未设置时，如果同级包含 `mustQueries` 或 `filterQueries`，默认值为 `0`；其他包含 `shouldQueries` 的情况默认值为 `1`。
weight（可选）	Float	组合查询权重。未设置时按 `1.0` 处理。值越大，`mustQueries` 和 `shouldQueries` 对最终相关性得分的贡献越大，不改变匹配范围。

说明

setMinimumShouldMatch(Integer) 已弃用。请使用 setMinShouldMatch(int) 或 setMinShouldMatch(String)。

返回列

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()` 获取。可从该字段读取相关性得分和摘要与高亮结果。
nextToken	byte[]	下一页凭证，通过 `getNextToken()` 获取。值不为 `null` 时，将其设置到下一次请求的 `token` 中继续读取。
isAllSuccess	boolean	是否已成功查询全部索引分区，通过 `isAllSuccess()` 获取。值为 `false` 时，返回的是部分结果，`totalCount` 可能小于实际匹配行数。

查询命中

response.searchHits[] 的类型为 SearchHit，包含以下核心字段。

名称	类型	说明
row	Row	命中的行数据，通过 `getRow()` 获取。
score	Double	相关性得分，通过 `getScore()` 获取。使用 `ScoreSort` 按相关性得分排序时返回实际得分。
highlightResultItem	HighlightResultItem	摘要与高亮结果，通过 `getHighlightResultItem()` 获取。

场景示例

满足任意一个条件

使用 shouldQueries 组合多个条件，并通过 minShouldMatch 指定至少满足的条件数。以下示例查询 city 等于 hangzhou 或 category 等于 book 的数据。

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(cityQuery, categoryQuery));
boolQuery.setMinShouldMatch(1);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

排除满足指定条件的数据

使用 mustNotQueries 排除满足任一指定条件的数据。以下示例查询 city 不等于 hangzhou 的数据。

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustNotQueries(Collections.singletonList(cityQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

过滤多个条件但不参与相关性算分

使用 filterQueries 要求数据满足所有子查询，但不让这些条件参与相关性算分。以下示例查询 city 等于 hangzhou 且 category 等于 book 的数据。

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setFilterQueries(Arrays.asList(cityQuery, categoryQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

嵌套组合多个条件

将 BoolQuery 作为另一个 BoolQuery 的子查询，可表达多层逻辑。以下示例实现 (city = "hangzhou" OR price < 150) OR (category = "book" AND (price = 300 OR price = 400))。

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

RangeQuery lowPriceQuery = new RangeQuery();
lowPriceQuery.setFieldName("price");
lowPriceQuery.lessThan(ColumnValue.fromLong(150));

BoolQuery firstGroup = new BoolQuery();
firstGroup.setShouldQueries(Arrays.asList(cityQuery, lowPriceQuery));

TermQuery price300Query = new TermQuery();
price300Query.setFieldName("price");
price300Query.setTerm(ColumnValue.fromLong(300));

TermQuery price400Query = new TermQuery();
price400Query.setFieldName("price");
price400Query.setTerm(ColumnValue.fromLong(400));

BoolQuery priceGroup = new BoolQuery();
priceGroup.setShouldQueries(Arrays.asList(price300Query, price400Query));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery secondGroup = new BoolQuery();
secondGroup.setMustQueries(Arrays.asList(categoryQuery, priceGroup));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(firstGroup, secondGroup));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);