サマリーとハイライト - Tablestore SDK for Python - Tablestore

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化します。

サマリーとハイライト機能を利用するには、SDK バージョン 6.0.0 以降が必要です。最新の SDK バージョンを使用することを推奨します。

検索インデックスを作成する際に、ターゲットの Text フィールドに対して enable_highlighting を True に設定します。

説明

サマリーとハイライトは、一致するトークン周辺のテキストフラグメントを抽出し、そのトークンを pre タグと post タグでマークします。この機能は Text フィールドのみをサポートします。クエリでは、SearchQuery.highlight を使用して、フィールドとフラグメント構成を指定します。

Tablestore SDK for Python 6.4.6 は、TermQuery、TermsQuery、PrefixQuery、WildcardQuery、RangeQuery、BoolQuery、MatchQuery、および MatchPhraseQuery のサマリーとハイライトをサポートします。 BoolQuery の場合、サポートされている子クエリタイプが使用するフィールドをハイライトできます。 NestedQuery の場合、InnerHits.highlight で一致する子行のハイライトを設定します。詳細については、「Nested クエリ」をご参照ください。

説明

MatchQuery または MatchPhraseQuery では、一致したトークンが複数の pre-tag と post-tag のペアでマークされることがあります。MatchPhraseQuery は、最大セマンティックアナライザーを使用する Text フィールドのハイライトをサポートしていません。フラグメントの境界によって一致したトークンが分割され、そのトークンがハイライトされなくなることがあります。

次の例では、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 の 2 つの設定レベルについて説明します。

名前	タイプ	説明
highlight_parameters (必須)	`list[HighlightParameter]`	フィールドのハイライトフラグメント設定です。各フィールドではハイライトを有効にし、ハイライトをサポートするクエリタイプで使用する必要があります。
highlight_encoder (オプション)	`HighlightEncoder`	フラグメントテキストのエンコーディングモード。`PLAIN_MODE` (デフォルト) はテキストをエンコードしません。`HTML_MODE` は `<`、`>`、`"`、`'`、`/` をそれぞれ `<`、`>`、`"`、`'`、`/` にエスケープし、Web 表示に適しています。
highlight_parameters[].field_name (必須)	`str`	フラグメントとハイライトを返す `Text` フィールドの名前。
highlight_parameters[].number_of_fragments (オプション)	`int`	フィールドから返されるフラグメントの最大数です。`1` を推奨します。
highlight_parameters[].fragment_size (オプション)	`int`	The target fragment length. Default value: `100`. The actual length may differ.
highlight_parameters[].pre_tag (オプション)	`str`	マッチしたトークン用の開始タグです。デフォルト値は `<em>` です。このパラメーターは `post_tag` と共に指定します。タグには `<`、`>`、`"`、`'`、`/`、`a-z`、`A-Z`、および `0-9` を含めることができます。
highlight_parameters[].post_tag (オプション)	`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 (オプション)	`HighlightFragmentOrder`	フラグメントの並べ替え順序。 `TEXT_SEQUENCE` (デフォルト) は元のテキスト位置順に並べ替え、`SCORE` はトークンの関連性スコアに基づいて並べ替えます。

レスポンス

ハイライト結果は SearchResponse.search_hits[].highlight_result にあり、構造は以下のとおりです。

フィールド	タイプ	説明
search_hits	`list[SearchHit]`	検索ヒットです。
search_hits[].row	`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`	ハイライトされたフィールド名です。
highlight_fields[].field_fragments	`list[str]`	The highlighted fragments. Matching tokens are marked by the configured tags.

タプル互換レスポンス

Tablestore SDK for Python 5.2.0 以降、検索 API はタプルの代わりにレスポンスオブジェクトを返します。バージョン 5.1.0 以前はタプルを直接返します。バージョン 5.2.1 以降では、SearchResponse.v1_response() を呼び出して、以前のバージョンと互換性のあるタプルを取得できます。新しいコードでは、レスポンスフィールドが拡張された場合にアンパックエラーが発生するのを避けるため、SearchResponse の属性に直接アクセスしてください。

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