表格存储 Java SDK 摘要与高亮-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

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

功能说明

摘要与高亮用于从查询结果中提取命中词条附近的文本片段，并使用前置标签和后置标签标记命中词条，便于展示命中上下文。该功能仅支持 Text 类型字段。

使用摘要与高亮前，需要在创建多元索引时将目标字段的 enableHighlighting 设置为 true。查询时，通过 SearchQuery.highlight 指定要返回摘要与高亮结果的字段及分片配置。目标字段必须参与支持摘要与高亮的查询条件，否则不会返回该字段的高亮分片。

支持摘要与高亮的查询类型包括 TermQuery、TermsQuery、MatchQuery、MatchPhraseQuery、PrefixQuery、WildcardQuery、RangeQuery、BoolQuery、ConstScoreQuery 和 NestedQuery。

使用 BoolQuery 或 ConstScoreQuery 时，可为上述七种查询类型的子查询所使用的字段配置摘要与高亮。使用 NestedQuery 查询嵌套类型字段时，需要通过 InnerHits.highlight 配置匹配子行的摘要与高亮，具体操作请参见嵌套类型查询。

说明

使用 MatchQuery 或 MatchPhraseQuery 时，同一个命中词条可能被多组前置标签和后置标签标记。
Text 字段使用最大数量语义分词时，MatchPhraseQuery 不支持摘要与高亮。
分片边界可能切分命中词条，导致该词条未被高亮。

以下示例使用匹配查询检索 description 字段中包含 tablestore 词条的数据，并使用 <b> 和 </b> 标记返回分片中的命中词条。description 字段为已启用摘要与高亮的 Text 字段。

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

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

HighlightParameter highlightParameter = new HighlightParameter();
highlightParameter.setPreTag("<b>");
highlightParameter.setPostTag("</b>");

Highlight highlight = new Highlight();
highlight.addFieldHighlightParam("description", highlightParameter);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);
searchQuery.setHighlight(highlight);
searchQuery.setLimit(10);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    HighlightResultItem resultItem = hit.getHighlightResultItem();
    if (resultItem == null) {
        continue;
    }
    HighlightField field = resultItem.getHighlightFieldByName("description");
    if (field != null) {
        System.out.println(field.getFragments());
    }
}

参数说明

request.searchQuery.highlight 的类型为 Highlight。其中，fieldHighlightParams 的值为 HighlightParameter，用于配置每个字段的分片行为。

下表使用完整参数路径说明 Highlight 和 HighlightParameter 两层配置。

名称	类型	说明
fieldHighlightParams（必选）	`Map<String, HighlightParameter>`	字段名称及其分片配置。键为要返回摘要与高亮结果的字段名称，值为该字段的 `HighlightParameter`。字段必须已启用摘要与高亮，并参与支持摘要与高亮的查询条件。
highlightEncoder（可选）	HighlightEncoder	高亮分片中原文的编码方式。取值如下： `PLAIN`（默认）：不编码原文。 `HTML`：对原文执行 HTML 转义，适用于在网页中展示结果。转义字符包括 `<`、`>`、`"`、`'` 和 `/`，分别转义为 `<`、`>`、`"`、`'` 和 `/`。
fieldHighlightParams[].numberOfFragments（可选）	Integer	单个字段返回的最大高亮分片数。建议设置为 `1`。
fieldHighlightParams[].fragmentSize（可选）	Integer	每个分片的目标长度。默认值为 `100`。实际返回长度可能与该值不同。
fieldHighlightParams[].preTag（可选）	String	命中词条的前置标签。默认值为 `<em>`，可自定义为 `<b>` 等标签。必须与 `postTag` 同时设置。支持字符 `< > " ' /`、`a-z`、`A-Z` 和 `0-9`。
fieldHighlightParams[].postTag（可选）	String	命中词条的后置标签。默认值为 `</em>`，可自定义为 `</b>` 等标签。必须与 `preTag` 同时设置，支持的字符与 `preTag` 相同。
fieldHighlightParams[].highlightFragmentOrder（可选）	HighlightFragmentOrder	返回多个高亮分片时的排序方式。`TEXT_SEQUENCE`（默认）按分片在原文中的位置排序；`SCORE` 按命中词条的相关性得分排序。

返回值

查询响应

search 方法返回 SearchResponse。与摘要与高亮相关的核心字段如下。

名称	类型	说明
searchHits	`List<SearchHit>`	查询命中结果，通过 `getSearchHits()` 获取。每个元素包含行数据和摘要与高亮结果。
isAllSuccess	boolean	是否已成功查询全部索引分区，通过 `isAllSuccess()` 获取。值为 `false` 时，返回的是部分结果。

查询命中

response.searchHits[] 的类型为 SearchHit。与摘要与高亮相关的字段如下。

名称	类型	说明
row	Row	命中的行数据，通过 `getRow()` 获取。
highlightResultItem	HighlightResultItem	当前行所有字段的摘要与高亮结果，通过 `getHighlightResultItem()` 获取。当前行没有高亮结果时为 `null`。

高亮结果

response.searchHits[].highlightResultItem 的类型为 HighlightResultItem，包含以下字段。

名称	类型	说明
highlightFields	`Map<String, HighlightField>`	当前行各字段的高亮结果，通过 `getHighlightFields()` 获取。也可调用 `getHighlightFieldByName(fieldName)` 获取指定字段的结果；该字段没有高亮结果时返回 `null`。

字段分片

response.searchHits[].highlightResultItem.highlightFields[fieldName] 的类型为 HighlightField，包含以下字段。

名称	类型	说明
fragments	`List<String>`	指定字段的高亮分片列表，通过 `getFragments()` 获取。分片中的命中词条已使用配置的前置标签和后置标签标记。