Table Store Python SDK 摘要與高亮 - 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()