Summary and highlighting - Tablestore SDK for Python - Tablestore

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

The summary and highlighting feature requires SDK version 6.0.0 or later. We recommend that you use the latest SDK version.

When creating the search index, you set enable_highlighting to True for the target Text field.

Description

Summary and highlighting extracts text fragments around matching tokens and marks the tokens with pre-tags and post-tags. This feature supports only Text fields. In a query, use SearchQuery.highlight to specify fields and fragment configurations.

Tablestore SDK for Python 6.4.6 supports summary and highlighting for TermQuery, TermsQuery, PrefixQuery, WildcardQuery, RangeQuery, BoolQuery, MatchQuery, and MatchPhraseQuery. For BoolQuery, you can highlight fields used by supported child-query types. For NestedQuery, configure matching child-row highlights in InnerHits.highlight. For more information, see Nested query.

Note

With MatchQuery or MatchPhraseQuery, a matching token may be marked by multiple pairs of pre-tags and post-tags. MatchPhraseQuery does not support highlighting for a Text field that uses the maximum semantic analyzer. A fragment boundary may split a matching token and prevent the token from being highlighted.

The following example queries the tablestore token in the description field and marks matching tokens in fragments with <b> and </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)

Parameters

search_query.highlight is of the Highlight type. The following table uses full paths to describe the two configuration levels of Highlight and HighlightParameter.

Name	Type	Description
highlight_parameters (required)	`list[HighlightParameter]`	The highlighted-fragment configurations for fields. Each field must have highlighting enabled and participate in a query type that supports highlighting.
highlight_encoder (optional)	`HighlightEncoder`	The fragment text encoding mode. `PLAIN_MODE` (default) does not encode text. `HTML_MODE` escapes `<`, `>`, `"`, `'`, and `/` as `<`, `>`, `"`, `'`, and `/`, respectively, and is suitable for web display.
highlight_parameters[].field_name (required)	`str`	The name of the `Text` field for which to return fragments and highlights.
highlight_parameters[].number_of_fragments (optional)	`int`	The maximum number of fragments to return for a field. We recommend `1`.
highlight_parameters[].fragment_size (optional)	`int`	The target fragment length. Default value: `100`. The actual length may differ.
highlight_parameters[].pre_tag (optional)	`str`	The pre-tag for matching tokens. Default value: `<em>`. Specify this parameter together with `post_tag`. The tag can contain `<`, `>`, `"`, `'`, `/`, `a-z`, `A-Z`, and `0-9`.
highlight_parameters[].post_tag (optional)	`str`	The post-tag for matching tokens. Default value: `</em>`. Specify this parameter together with `pre_tag`. The tag can contain `<`, `>`, `"`, `'`, `/`, `a-z`, `A-Z`, and `0-9`.
highlight_parameters[].fragments_order (optional)	`HighlightFragmentOrder`	The fragment sort order. `TEXT_SEQUENCE` (default) sorts by the original text position, and `SCORE` sorts by token relevance score.

Response

Highlight results are available at SearchResponse.search_hits[].highlight_result and have the following structure.

Field	Type	Description
search_hits	`list[SearchHit]`	The search hits.
search_hits[].row	`Row`	The matching row.
search_hits[].highlight_result	`HighlightResult`	The summary and highlighting result for the row. The value is empty if no highlight is returned.
search_hits[].highlight_result.highlight_fields	`list[HighlightField]`	The highlights for fields in the row.
highlight_fields[].field_name	`str`	The highlighted field name.
highlight_fields[].field_fragments	`list[str]`	The highlighted fragments. Matching tokens are marked by the configured tags.

Tuple-compatible response

Starting from Tablestore SDK for Python 5.2.0, search APIs return response objects instead of tuples. Version 5.1.0 and earlier return tuples directly. In version 5.2.1 and later, you can call SearchResponse.v1_response() to obtain a tuple compatible with earlier versions. For new code, access SearchResponse attributes directly to avoid unpacking errors if response fields are extended.

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