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

前提条件

摘要与高亮功能需要使用 6.0.0 及以上版本，建议使用最新版本的 SDK。

已在创建多元索引时将目标 Text 字段的 enable_highlighting 设置为 True。

功能说明

摘要与高亮用于提取命中词条附近的文本片段，并使用前置标签和后置标签标记命中词条。该功能仅支持 Text 字段。查询时，通过 SearchQuery.highlight 指定字段和分片配置。

Tablestore Python SDK 6.4.6 支持为 TermQuery、TermsQuery、PrefixQuery、WildcardQuery、RangeQuery、BoolQuery、MatchQuery 和 MatchPhraseQuery 配置摘要与高亮。使用 BoolQuery 时，可以为上述查询类型的子查询字段配置摘要与高亮。使用 NestedQuery 时，需要通过 InnerHits.highlight 配置匹配子行的摘要与高亮，具体请参见嵌套类型查询。

说明

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

以下示例查询 description 字段中的 tablestore 词条，并使用 <b> 和 </b> 标记高亮分片中的命中词条。

query = MatchQuery("description", "tablestore")
highlight = Highlight(
    [
        HighlightParameter(
            "description",
            number_of_fragments=1,
            fragment_size=100,
            pre_tag="<b>",
            post_tag="</b>",
        )
    ],
    HighlightEncoder.PLAIN_MODE,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10, highlight=highlight),
)
for hit in response.search_hits:
    for field in hit.highlight_result.highlight_fields:
        print(field.field_name, field.field_fragments)

参数说明

search_query.highlight 的类型为 Highlight。下表使用完整路径说明 Highlight 和 HighlightParameter 两层配置。

名称	类型	说明
highlight_parameters（必选）	`list[HighlightParameter]`	各字段的高亮分片配置。字段必须启用摘要与高亮，并参与支持摘要与高亮的查询条件。
highlight_encoder（可选）	`HighlightEncoder`	分片原文编码方式。`PLAIN_MODE`（默认）不编码；`HTML_MODE` 将 `<`、`>`、`"`、`'` 和 `/` 分别转义为 `<`、`>`、`"`、`'` 和 `/`，适合网页展示。
highlight_parameters[].field_name（必选）	`str`	要返回摘要与高亮结果的 `Text` 字段名称。
highlight_parameters[].number_of_fragments（可选）	`int`	单个字段返回的最大分片数，建议设置为 `1`。
highlight_parameters[].fragment_size（可选）	`int`	每个分片的目标长度，默认值为 `100`。实际返回长度可能不同。
highlight_parameters[].pre_tag（可选）	`str`	命中词条的前置标签，默认值为 `<em>`。必须与 `post_tag` 同时设置，可使用 `<`、`>`、`"`、`'`、`/`、`a-z`、`A-Z` 和 `0-9` 中的字符。
highlight_parameters[].post_tag（可选）	`str`	命中词条的后置标签，默认值为 `</em>`。必须与 `pre_tag` 同时设置，可使用 `<`、`>`、`"`、`'`、`/`、`a-z`、`A-Z` 和 `0-9` 中的字符。
highlight_parameters[].fragments_order（可选）	`HighlightFragmentOrder`	多个分片的排序方式。`TEXT_SEQUENCE`（默认）按原文位置排序；`SCORE` 按命中词条的相关性得分排序。

返回值

高亮结果位于 SearchResponse.search_hits[].highlight_result，层级如下。

字段	类型	说明
search_hits	`list[SearchHit]`	查询命中结果。
search_hits[].row	`Row`	命中的行数据。
search_hits[].highlight_result	`HighlightResult`	当前行的摘要与高亮结果。没有高亮结果时为空。
search_hits[].highlight_result.highlight_fields	`list[HighlightField]`	当前行各字段的高亮结果。
highlight_fields[].field_name	`str`	高亮字段名称。
highlight_fields[].field_fragments	`list[str]`	高亮分片列表，命中词条已由配置的标签标记。

兼容 Tuple 返回格式

Tablestore Python SDK 5.2.0 开始将查询接口的返回值由 Tuple 调整为响应对象，5.1.0 及以下版本直接返回 Tuple。5.2.1 及以上版本可调用 SearchResponse.v1_response() 获取与旧版本兼容的 Tuple。新代码建议直接访问 SearchResponse 的属性，避免返回字段扩展后解包数量不匹配。

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()