terms クエリ - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

前提条件

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

説明

Terms クエリは、フィールド内の複数の値に一致します。いずれかのクエリ値と完全一致する場合、その行は一致します。Keyword や Long などの非テキストフィールドの場合、フィールド値がいずれかのクエリ値と完全に一致する必要があります。これは、SQL の IN 条件に似ています。Text フィールドの場合、1 つのトークンがいずれかのクエリ値と完全に一致すると、行が一致します。クエリ値はトークン化されません。トークン化は、アナライザーの設定、アルゴリズムの更新、および言語によって異なる場合があります。Text フィールド内の完全な文字列を照合するために Terms クエリを使用しないでください。search メソッドを呼び出すときは、クエリタイプを TermsQuery に設定します。フィールドタイプの詳細については、「文字列型」をご参照ください。

TermsQuery(field_name, column_values, weight=None)

次の例では、category フィールドが books または games と完全に一致する行を照会し、最大 10 行と一致する行の総数を返します。

query = TermsQuery("category", ["books", "games"])
search_query = SearchQuery(
    query,
    limit=10,
    get_total_count=True,
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.total_count)
for row in response.rows:
    print(row)

パラメーター

検索リクエスト

search メソッドには、以下のパラメーターが含まれています。

名前	型	説明
table_name (必須)	`str`	データテーブルの名前。
index_name (必須)	`str`	検索インデックスの名前。
search_query (必須)	`SearchQuery`	クエリ条件と共通のクエリ設定。
columns_to_get (任意)	`ColumnsToGet`	取得する列の設定。このパラメーターを指定しない場合、プライマリキー列のみが返されます。
routing_keys (任意)	`list`	カスタムルーティングフィールドのプライマリキー値のリスト。カスタムルーティングが設定されていない場合、このパラメーターを指定する必要はありません。
timeout_s (任意)	`int`	リクエストのタイムアウト (秒単位)。このパラメーターを指定しない場合、クライアントレベルのタイムアウトが使用されます。

クエリ設定

search_query は SearchQuery 型であり、以下のパラメーターを含みます。

名前	型	説明
query (必須)	`クエリ`	クエリ条件。このパラメーターを`TermsQuery`に設定します。
sort (任意)	`ソート`	クエリ結果のソート順。詳細については、「結果のソートとページ分割」をご参照ください。
get_total_count (任意)	`ブール`	一致する行の総数を返すかどうかを指定します。デフォルト値は `False` です。このパラメーターを `True` に設定すると、クエリのオーバーヘッドが増加します。
next_token (任意)	`バイト`	ページネショントークン。次のページを取得するには、このパラメーターに前回のレスポンスの `next_token` を設定します。詳細については、「結果の並べ替えとページネーション」をご参照ください。
offset (任意)	`int`	現在のクエリが開始されるオフセット。このパラメーターは、シャローページネーションに使用します。
limit (任意)	`int`	返す行の最大数。このパラメーターを `0` に設定すると、行データは返されません。
aggs (任意)	`list[Agg]`	集約設定。詳細については、「集約」をご参照ください。
group_bys (任意)	`list[BaseGroupBy]`	グループ化設定。詳細については、「集約」をご参照ください。
collapse_field (任意)	`折りたたむ`	結果の折りたたみ設定。指定したフィールドに基づいて重複する結果を削除します。詳細については、「クエリ結果の折りたたみ」をご参照ください。
highlight (任意)	`ハイライト`	`Text` フィールドのサマリーとハイライトの設定です。詳細については、「サマリーとハイライト」をご参照ください。

クエリ条件

search_query.query は TermsQuery 型であり、次のパラメーターを含みます。

名前	型	説明
field_name (必須)	`str`	クエリ対象のインデックス付きフィールドの名前。
column_values (必須)	`list`	クエリ値のリストです。最大 1,024 個の値を指定できます。クエリ値のいずれかと完全一致する場合、その行は一致しているとみなされます。`Text` フィールドの場合、各値は完全なトークンとして使用され、トークン化されません。
weight (任意)	`float`	クエリ条件の関連性の重みです。値は正の浮動小数点数である必要があります。値が大きいほど、BM25 関連性スコアへの寄与が大きくなります。このパラメーターは、マッチングや返される行数には影響しません。結果が関連性スコアによってソートされる場合にのみ、順序に影響します。デフォルト値： `1.0`。

返される列

columns_to_get は ColumnsToGet 型で、以下のパラメーターを含みます。

名前	型	説明
column_names (任意)	`list[str]`	返される属性列の名前。このパラメーターは `return_type` が `SPECIFIED` の場合にのみ指定します。
return_type (任意)	`ColumnReturnType`	返される列のモードです。`NONE` (デフォルト) はプライマリキー列のみを返し、`SPECIFIED` は `column_names` の属性列を返し、`ALL` はテーブルのすべての属性列を返し、`ALL_FROM_INDEX` はインデックスが作成されたすべての属性列を返します。

レスポンス

search メソッドは SearchResponse を返します。次の表では、コアフィールドについて説明します。

フィールド	型	説明
rows	`リスト[行]`	現在のクエリによって返される行。行数は `limit` を超えません。
next_token	`バイト`	次のページのトークン。このフィールドが空でない場合は、次のリクエストでこの値を渡して読み取りを続行します。
total_count	`int`	一致した行数です。この値は `get_total_count` 設定によって異なります。
is_all_succeed	`bool`	すべてのインデックスパーティションがクエリされたかどうかを示します。値が `False` の場合、部分的な結果が返され、`total_count` は実際に一致する行数より少なくなる可能性があります。
agg_results	`list[AggResult]`	集計結果。 `aggs` が設定されていない場合は空になります。
group_by_results	`list[GroupByResult]`	グルーピングの結果。 `group_bys` が設定されていない場合、このフィールドは空になります。
search_hits	`list[SearchHit]`	検索ヒット。関連度スコア、ハイライト、一致する子行などの拡張情報が含まれます。

タプル互換のレスポンス

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()