查询词高亮显示 - 表格存储

要使用查询摘要与高亮功能，您需要在创建多元索引时为Text类型的字段开启摘要与高亮（Highlight）功能，然后在查询数据时通过设置高亮参数，返回命中查询词的片段信息并对查询词进行高亮显示。

场景

查询摘要与高亮功能可用于全文检索场景中抽取命中查询词附近的片段并高亮命中的查询词，适用于网页搜索、聊天记录检索、文档搜索等场景。

功能概述

查询摘要与高亮功能可用于在搜索结果中对与查询词匹配或相关的文本进行高亮显示，帮助用户快速识别到所需的相关查询内容，提高信息检索的效率。对于包含嵌套类型的复杂数据结构（例如JSON）也支持使用查询摘要与高亮功能来精准定位所需信息。表格存储默认使用<em></em>标签来标记匹配的查询词。

要使用查询摘要与高亮功能，您需要完成如下配置：

在创建多元索引时，设置Text类型字段的enableHighlighting参数为True。具体操作，请参见创建多元索引。
重要
只支持为Text类型字段开启查询摘要与高亮功能。
在数据查询中使用查询摘要与高亮功能时，通过指定高亮分片的编码方式、返回高亮分片的最大数量、前置Tag、后置Tag等参数来自定义高亮显示的样式。

假设创建多元索引时已为某个Text类型字段开启查询摘要与高亮功能，当该Text类型字段的值为查询高亮测试时，在通过MatchPhrase功能查询关键词高亮，并指定高亮参数后，可返回高亮片段查询<em>高亮</em>测试。

注意事项

在MatchQuery和MatchPhraseQuery中使用查询摘要与高亮功能时，查询词可能会被多个preTag、postTag高亮显示。
如果Text字段的分词类型为最大语义分词，则使用MatchPhraseQuery功能进行数据查询时不支持使用查询摘要与高亮功能。
分片切分可能会将文本中的查询词分割，此时该查询词可能不会被高亮。

接口

查询摘要与高亮功能的接口为Search，具体的Query类型支持TermQuery、TermsQuery、MatchQuery、MatchPhraseQuery、PrefixQuery、WildcardQuery和NestedQuery。

参数

使用查询摘要与高亮功能时，一般情况下通过Highlight参数设置高亮参数。对于嵌套类型的子列，则需要通过InnerHits参数设置高亮参数。

Highlight参数

参数		说明
highlightEncoder		对高亮分片原文内容的编码方式。取值范围如下： PLAIN（默认）：原文展示，不进行编码。 HTML：对高亮分片原文进行HTML转义，转义包括`<`转义为`<`、`>`转义为`>`、`"`转义为`"`、`'`转义为`'`、`/`转义为`/`，网页展示时推荐使用HTML格式。
fieldHighlightParams		字段高亮参数，仅支持设置SearchQuery中包含关键词查询的字段。
HighlightParameter	numberOfFragments	返回高亮分片的最大数量，推荐设置为1。
	fragmentSize	每个分片的长度。默认值100。重要实际返回分片的长度不会与该值严格相等。
	preTag	查询词高亮的前置Tag，例如`<em>`、`<b>`。默认值为`<em>`，您可以按需自定义前置Tag。preTag支持的字符集包括`< > " ' /`、`a-z`、`A-Z`、`0-9`。
	postTag	查询词高亮的后置Tag，例如`</em>`、`</b>`。默认值为`</em>`，您可以按需自定义前置Tag。postTag支持的字符集包括`< > " ' /`、`a-z`、`A-Z`、`0-9`。
	highlightFragmentOrder	当高亮字段返回多个分片时，分片的排序规则。 TEXT_SEQUENCE（默认）：片段在文本中出现的顺序。 SCORE：根据命中查询词评分排序多个分片。

InnerHits参数

参数	说明
sort	Nested子行返回时的排序规则。
offset	当Nested列包含多个子行时，子行返回的起始位置。
limit	当Nested列包含多个子行时，返回子行的数量。默认值为3。
highlight	Nested子列高亮参数配置。具体配置说明请参见Highlight参数。

使用方式

重要

只支持通过SDK方式使用查询摘要与高亮功能。

进行高亮查询之前，您需要完成如下准备工作。

使用阿里云账号或者具有表格存储操作权限的RAM用户进行操作。如果需要为RAM用户授权表格存储操作权限，请参见通过RAM Policy为RAM用户授权进行配置。
使用SDK方式进行操作时，如果当前无可用AccessKey，则需要为阿里云账号或者RAM用户创建AccessKey。具体操作，请参见创建AccessKey。
已创建数据表。具体操作，请参见数据表操作。
已为数据表创建多元索引且为指定字段开启了高亮查询功能。具体操作，请参见创建多元索引。
使用SDK方式进行操作时，还需要完成初始化Client。具体操作，请参见初始化OTSClient。

您可以通过Java SDK、Go SDK、Python SDK和Node.js SDK使用查询摘要与高亮功能。此处以Java SDK为例介绍查询摘要与高亮功能的使用。

查询非嵌套类型字段时使用查询摘要与高亮

以下示例用于使用MatchQuery功能查询表中Col_Text列的值能够匹配hangzhou shanghai的数据，并在返回结果中对查询词进行高亮显示。其中Col_Text列为Text类型。

/**
 * MatchQuery查询摘要与高亮。
 */
public static void matchQueryWithHighlighting(SyncClient client) {
    SearchRequest searchRequest = SearchRequest.newBuilder()
            .tableName("<TABLE_NAME>")
            .indexName("<SEARCH_INDEX_NAME>")
            .returnAllColumnsFromIndex(true)
            .searchQuery(SearchQuery.newBuilder()
                    .limit(5)
                    .query(QueryBuilders.bool()
                            .should(QueryBuilders.match("Col_Text", "hangzhou shanghai")))
                    .highlight(Highlight.newBuilder()
                            .addFieldHighlightParam("Col_Text", HighlightParameter.newBuilder()
                                    .highlightFragmentOrder(HighlightFragmentOrder.TEXT_SEQUENCE)
                                    .preTag("<b>")
                                    .postTag("</b>")
                                    .build())
                            .build())
                    .build())
            .build();
    SearchResponse resp = client.search(searchRequest);

    // 打印查询和高亮结果。查询非嵌套类型字段时设置prefix为空即可。
    printSearchHit(resp.getSearchHits(), "");
}

/**
 * 打印searchHit内容。
 * @param searchHits searchHits
 * @param prefix Nested结构输出时，增加前缀以打印层次信息。
 */
private static void printSearchHit(List<SearchHit> searchHits, String prefix) {
    for (SearchHit searchHit : searchHits) {
        if (searchHit.getScore() != null) {
            System.out.printf("%s Score: %s\n", prefix, searchHit.getScore());
        }

        if (searchHit.getOffset() != null) {
            System.out.printf("%s Offset: %s\n", prefix, searchHit.getOffset());
        }

        if (searchHit.getRow() != null) {
            System.out.printf("%s Row: %s\n", prefix, searchHit.getRow().toString());
        }

        // 打印各字段高亮分片结果。
        if (searchHit.getHighlightResultItem() != null) {
            System.out.printf("%s Highlight: \n", prefix);
            StringBuilder strBuilder = new StringBuilder();
            for (Map.Entry<String, HighlightField> entry : searchHit.getHighlightResultItem().getHighlightFields().entrySet()) {
                strBuilder.append(entry.getKey()).append(":").append("[");
                strBuilder.append(StringUtils.join(",", entry.getValue().getFragments())).append("]\n");
            }
            System.out.printf("%s   %s", prefix, strBuilder);
        }

        System.out.println();
    }
}

查询嵌套类型字段时使用查询摘要与高亮

以下示例用于使用NestedQuery功能查询表中Col_Nested嵌套类型字段中Level1_Col1_Nested子列的值能够匹配hangzhou shanghai的数据，并在返回结果中对关键词进行高亮显示。

/**
 * NestedQuery查询高亮，通过innerHits设置参数。
 */
public static void NestedQueryQueryWithHighlighting1(SyncClient client) {
        SearchRequest searchRequest = SearchRequest.newBuilder()
                .tableName("<TABLE_NAME>")
                .indexName("<SEARCH_INDEX_NAME>")
                .returnAllColumnsFromIndex(true)
                .searchQuery(SearchQuery.newBuilder()
                        .limit(5)
                        .query(QueryBuilders.nested()
                                .path("Col_Nested")
                                .scoreMode(ScoreMode.Min)
                                .query(QueryBuilders.match("Col_Nested.Level1_Colqia1_Nested", "hangzhou shanghai"))
                                .innerHits(InnerHits.newBuilder()
                                        .highlight(Highlight.newBuilder()
                                                .addFieldHighlightParam("Col_Nested.Level1_Col1_Nested", HighlightParameter.newBuilder().build())
                                                .build())
                                        .build()))
                        .build())
                .build();
        SearchResponse resp = client.search(searchRequest);

        // 打印高亮结果。
        printSearchHit(resp.getSearchHits(), "");
}

/**
 * 打印searchHit内容。
 * @param searchHits searchHits
 * @param prefix Nested结构输出时，增加前缀以打印层次信息。
 */
private static void printSearchHit(List<SearchHit> searchHits, String prefix) {
    for (SearchHit searchHit : searchHits) {
        if (searchHit.getScore() != null) {
            System.out.printf("%s Score: %s\n", prefix, searchHit.getScore());
        }

        if (searchHit.getOffset() != null) {
            System.out.printf("%s Offset: %s\n", prefix, searchHit.getOffset());
        }

        if (searchHit.getRow() != null) {
            System.out.printf("%s Row: %s\n", prefix, searchHit.getRow().toString());
        }

        // 打印各字段高亮分片结果。
        if (searchHit.getHighlightResultItem() != null) {
            System.out.printf("%s Highlight: \n", prefix);
            StringBuilder strBuilder = new StringBuilder();
            for (Map.Entry<String, HighlightField> entry : searchHit.getHighlightResultItem().getHighlightFields().entrySet()) {
                strBuilder.append(entry.getKey()).append(":").append("[");
                strBuilder.append(StringUtils.join(",", entry.getValue().getFragments())).append("]\n");
            }
            System.out.printf("%s   %s", prefix, strBuilder);
        }

        // 嵌套类型高亮结果。
        for (SearchInnerHit searchInnerHit : searchHit.getSearchInnerHits().values()) {
            System.out.printf("%s Path: %s\n", prefix, searchInnerHit.getPath());
            System.out.printf("%s InnerHit: \n", prefix);
            printSearchHit(searchInnerHit.getSubSearchHits(), prefix + "    ");
        }

        System.out.println();
    }
}

假设多层级嵌套类型字段Col_Nested中包括Level1_Col1_Text（Text类型）和Level1_Col2_Nested（Nested类型）两列，其中Level1_Col2_Nested嵌套类型字段包括Level2_Col1_Text子列。

以下示例用于通过在NestedQuery中添加BoolQuery对Col_Nested字段中的Level1_Col1_Text子列和Level1_Col2_Nested下的Level2_Col1_Text子列同时使用查询高亮功能。

public static void NestedQueryWithHighlighting(SyncClient client) {
    SearchRequest searchRequest = SearchRequest.newBuilder()
        .tableName("<TABLE_NAME>")
        .indexName("<SEARCH_INDEX_NAME>")
        .returnAllColumnsFromIndex(true)
        .searchQuery(SearchQuery.newBuilder()
            .limit(5)
            .query(QueryBuilders.nested()
                .path("Col_Nested")
                .scoreMode(ScoreMode.Min)
                .query(QueryBuilders.bool()
                    .should(QueryBuilders.match("Col_Nested.Level1_Col1_Text", "hangzhou shanghai"))
                    .should(QueryBuilders.nested()
                        .path("Col_Nested.Level1_Col2_Nested")
                        .scoreMode(ScoreMode.Min)
                        .query(QueryBuilders.match("Col_Nested.Level1_Col2_Nested.Level2_Col1_Text", "hangzhou shanghai"))
                        .innerHits(InnerHits.newBuilder()
                            .highlight(Highlight.newBuilder()
                                .addFieldHighlightParam("Col_Nested.Level1_Col2_Nested.Level2_Col1_Text", HighlightParameter.newBuilder().build())
                                .build())
                            .build())))
                .innerHits(InnerHits.newBuilder()
                    .sort(new Sort(Arrays.asList(
                        new ScoreSort(),
                        new DocSort()
                    )))
                    .highlight(Highlight.newBuilder()
                        .addFieldHighlightParam("Col_Nested.Level1_Col1_Text", HighlightParameter.newBuilder().build())
                        .build())
                .build())))
        .build();
    SearchResponse resp = client.search(searchRequest);

    // 打印高亮结果。
    printSearchHit(resp.getSearchHits(), "");
}

/**
 * 打印searchHit内容。
 * @param searchHits searchHits
 * @param prefix Nested结构输出时，增加前缀以打印层次信息。
 */
private static void printSearchHit(List<SearchHit> searchHits, String prefix) {
    for (SearchHit searchHit : searchHits) {
        if (searchHit.getScore() != null) {
            System.out.printf("%s Score: %s\n", prefix, searchHit.getScore());
        }

        if (searchHit.getOffset() != null) {
            System.out.printf("%s Offset: %s\n", prefix, searchHit.getOffset());
        }

        if (searchHit.getRow() != null) {
            System.out.printf("%s Row: %s\n", prefix, searchHit.getRow().toString());
        }

        // 打印各字段高亮分片结果。
        if (searchHit.getHighlightResultItem() != null) {
            System.out.printf("%s Highlight: \n", prefix);
            StringBuilder strBuilder = new StringBuilder();
            for (Map.Entry<String, HighlightField> entry : searchHit.getHighlightResultItem().getHighlightFields().entrySet()) {
                strBuilder.append(entry.getKey()).append(":").append("[");
                strBuilder.append(StringUtils.join(",", entry.getValue().getFragments())).append("]\n");
            }
            System.out.printf("%s   %s", prefix, strBuilder);
        }

        // 嵌套类型高亮结果。
        for (SearchInnerHit searchInnerHit : searchHit.getSearchInnerHits().values()) {
            System.out.printf("%s Path: %s\n", prefix, searchInnerHit.getPath());
            System.out.printf("%s InnerHit: \n", prefix);
            printSearchHit(searchInnerHit.getSubSearchHits(), prefix + "    ");
        }

        System.out.println();
    }
}

计费说明

在数据查询时使用查询摘要与高亮功能不影响现有计费规则。

使用多元索引查询数据时会消耗读吞吐量。更多信息，请参见多元索引计量计费。

表格存储：摘要与高亮

场景