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

前提条件

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

説明

検索インデックスの範囲クエリは、フィールド値が指定された範囲内にある行に一致します。下限のみ、上限のみ、またはその両方を指定できますが、少なくとも 1 つの境界が必要です。Text フィールドの場合、1 つのトークンが範囲内にあると行が一致します。search メソッドを呼び出すときは、クエリタイプを RangeQuery に設定します。

RangeQuery(field_name, range_from=None, range_to=None, include_lower=True, include_upper=False)

次の例では、price フィールドが左閉右開区間 [100, 500) にある行をクエリし、最大 10 行と一致する行の総数を返します。

query = RangeQuery(
    "price",
    range_from=100,
    range_to=500,
    include_lower=True,
    include_upper=False,
)
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 (必須)	`クエリ`	クエリ条件。このパラメーターを `RangeQuery` に設定します。
sort (オプション)	`ソート`	クエリ結果のソート順。詳細については、「結果のソートとページ分割」をご参照ください。
get_total_count (オプション)	`bool`	一致する行の総数を返すかどうかを指定します。デフォルト値は `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 は RangeQuery 型で、次のパラメーターを含みます。

名前	タイプ	説明
field_name (必須)	`str`	クエリ対象のインデックスフィールド名。範囲クエリは、`Long`、`Double`、`Boolean`、`Keyword`、`Text`、および `Date` の各フィールド、および JSON オブジェクトフィールドの子フィールドをサポートします。`Text` フィールドの場合、トークンが 1 つでも範囲内にあれば、その行は一致します。
range_from (オプション)	`str / int / float / bool`	下限。`range_from` と `range_to` の少なくとも 1 つを指定する必要があります。
range_to (オプション)	`str / int / float / bool`	上限。 `range_from` と `range_to` のうち、少なくとも 1 つを指定する必要があります。
include_lower (オプション)	`bool`	下限値を含めるかどうかを指定します。デフォルト値は `True` です。
include_upper (オプション)	`bool`	上限を含めるかどうかを指定します。デフォルト値は `False` です。

取得する列

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	`list[Row]`	現在のクエリによって返される行です。行数は `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()