表格存储 Java SDK 嵌套类型查询-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

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

功能说明

嵌套类型查询用于查询 Nested 类型字段中的子行。Nested 字段的每个子行独立保留字段间的对应关系，不能直接按其子字段查询，需要使用 NestedQuery 包裹子查询。

NestedQuery.path 指定要查询的嵌套字段路径，子查询中的字段名称需要使用完整路径。子查询可以是任意 Query 类型。多层嵌套字段可以直接将 path 设置为目标嵌套字段的完整路径，也可以使用多层 NestedQuery 逐层查询。

多个条件是否必须由同一个子行满足，取决于 NestedQuery 与 BoolQuery 的组合方式：

同一个子行必须满足多个条件时，将包含多个子条件的 BoolQuery 设置为一个 NestedQuery 的子查询。
不同子行可以分别满足多个条件时，为每个条件分别构造 NestedQuery，再使用外层 BoolQuery 组合。

调用 search 方法执行嵌套类型查询。查询条件需要指定嵌套字段路径、子查询和评分模式。

SearchResponse search(SearchRequest request)

以下示例查询 items 嵌套字段中，items.keyword 等于 tablestore 的子行，返回最多 10 行数据及匹配总行数。

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

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(termQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
System.out.println(response.getTotalCount());
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	查询条件。嵌套类型查询设置为 `NestedQuery`。
offset（可选）	Integer	本次查询的起始位置。
limit（可选）	Integer	本次查询返回的最大行数。设置为 `0` 时不返回具体行。
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 的类型为 NestedQuery，包含以下参数。

名称	类型	说明
path（必选）	String	要查询的嵌套字段路径。查询多层嵌套字段时，设置为目标嵌套字段的完整路径，例如 `items.details`。
query（必选）	Query	在 `path` 对应的子行中执行的查询条件，可以是任意 `Query` 类型。子字段名称需要使用完整路径，例如 `items.keyword`。
scoreMode（必选）	ScoreMode	多个子行匹配时的父行评分方式。`None` 不计算子行相关性得分；`Avg`、`Max`、`Min` 和 `Total` 分别使用子行得分的平均值、最大值、最小值和总和。
innerHits（可选）	InnerHits	匹配子行的返回、排序、分页和高亮配置。未设置时不返回匹配子行的明细。
weight（可选）	float	查询权重，默认值为 `1.0`，取值为正浮点数。值越大，匹配行的得分越高；该参数不改变匹配范围。

子行返回配置

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

名称	类型	说明
sort（可选）	Sort	匹配子行的排序方式。可使用 `ScoreSort` 和 `DocSort`；不支持 `FieldSort`。
offset（可选）	Integer	返回匹配子行的起始位置。
limit（可选）	Integer	返回匹配子行的最大数量，默认值为 `3`。
highlight（可选）	Highlight	匹配子行的高亮配置。有关高亮字段和参数的配置方法，请参见摘要与高亮。

返回列

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

查询命中

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

名称	类型	说明
row	Row	命中的行或子行数据，通过 `getRow()` 获取。
score	Double	相关性得分，通过 `getScore()` 获取。
offset	Integer	嵌套子行在原数组中的位置，通过 `getOffset()` 获取。父行命中结果中该字段可能为空。
highlightResultItem	HighlightResultItem	高亮结果，通过 `getHighlightResultItem()` 获取。
searchInnerHits	`Map<String, SearchInnerHit>`	按嵌套字段路径组织的匹配子行，通过 `getSearchInnerHits()` 获取；也可以通过 `getSearchInnerHitByPath(path)` 获取指定路径的结果。

嵌套命中

response.searchHits[].searchInnerHits 的值类型为 SearchInnerHit，包含以下字段。

名称	类型	说明
path	String	嵌套字段路径，通过 `getPath()` 获取。
subSearchHits	`List<SearchHit>`	匹配的子行，通过 `getSubSearchHits()` 获取。多层嵌套查询中，子行的 `searchInnerHits` 可继续包含下一层匹配结果。

场景示例

查询多层嵌套字段

查询多层嵌套字段时，将 path 设置为目标嵌套字段的完整路径，并在子查询中指定子字段的完整路径。以下示例查询 items.details.name 等于 beta 的数据。

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.details.name");
termQuery.setTerm(ColumnValue.fromString("beta"));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items.details");
nestedQuery.setQuery(termQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

同一子行满足多个条件

将包含多个子条件的 BoolQuery 设置为一个 NestedQuery 的子查询。以下示例要求 items 中存在同一个子行，同时满足 items.keyword 等于 tablestore 且 items.number 存在。

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.number");

BoolQuery childQuery = new BoolQuery();
childQuery.setMustQueries(Arrays.asList(termQuery, existsQuery));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(childQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

不同子行满足多个条件

为每个条件分别构造 NestedQuery，再使用外层 BoolQuery 组合。以下示例允许 items.keyword 等于 tablestore 和 items.number 存在两个条件由不同子行分别满足。

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));
NestedQuery termNestedQuery = new NestedQuery();
termNestedQuery.setPath("items");
termNestedQuery.setQuery(termQuery);
termNestedQuery.setScoreMode(ScoreMode.None);

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.number");
NestedQuery existsNestedQuery = new NestedQuery();
existsNestedQuery.setPath("items");
existsNestedQuery.setQuery(existsQuery);
existsNestedQuery.setScoreMode(ScoreMode.None);

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(
        Arrays.asList(termNestedQuery, existsNestedQuery));

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

返回并高亮匹配的子行

通过 InnerHits 配置匹配子行的返回数量、排序和高亮。以下示例查询 items.description 中包含 hangzhou 的子行，并返回高亮结果。

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("items.description");
matchQuery.setText("hangzhou");

HighlightParameter parameter = new HighlightParameter();
parameter.setPreTag("<em>");
parameter.setPostTag("</em>");
Highlight highlight = new Highlight();
highlight.addFieldHighlightParam("items.description", parameter);

InnerHits innerHits = new InnerHits();
innerHits.setLimit(3);
innerHits.setSort(new Sort(Arrays.asList(
        new ScoreSort(), new DocSort(SortOrder.ASC))));
innerHits.setHighlight(highlight);

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(matchQuery);
nestedQuery.setScoreMode(ScoreMode.None);
nestedQuery.setInnerHits(innerHits);

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

多层嵌套查询需要在哪一层返回或高亮匹配子行，就在对应层的 NestedQuery 中分别设置 innerHits。