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

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化しておく必要があります。

ターゲットフィールドは、検索インデックス内で Object フィールドまたは Nested JSON フィールドとして設定されます。詳細については、「検索インデックスの作成」をご参照ください。

説明

JSON クエリには専用のクエリタイプがありません。検索インデックス内の JSON フィールドの json_type に基づいて、クエリ方法を選択します。

JSON タイプ	説明
Object	配列内で子オブジェクトの境界を保持しません。子フィールドの型と照合要件に適したクエリタイプを直接使用し、子フィールドの完全なパスを指定します。異なる条件は、異なる子オブジェクトによって満たされることがあります。
Nested	配列内の各子オブジェクトを独立した子行として扱い、フィールド間の関係を保持します。子クエリを `NestedQuery` でラップし、`path` に Nested フィールドのパスを指定します。内部のすべての条件は、同一の子行によって満たされる必要があります。

例えば、address 配列に {"country":"China","city":"hangzhou"} と {"country":"usa","city":"Seattle"} が含まれているとします。country=China と city=Seattle の両方を満たすクエリは、フィールドが Object の場合は行に一致しますが、フィールドが Nested の場合は一致しません。

説明

JSON フィールドの子フィールドを Vector フィールドにすることはできません。

Object フィールドのクエリ

profile.name が alice であり、profile.score が 80 以上の行をクエリします。

query = BoolQuery(
    must_queries=[
        TermQuery("profile.name", "alice"),
        RangeQuery("profile.score", range_from=80),
    ]
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
print(response.rows)

Nested フィールドのクエリ

次の例では、address 内の同一の子オブジェクトが、address.country が China であり、かつ address.city が Seattle であることを要件とします。その他の設定については、「Nested クエリ」をご参照ください。

child_query = BoolQuery(
    must_queries=[
        TermQuery("address.country", "China"),
        TermQuery("address.city", "Seattle"),
    ]
)
query = NestedQuery("address", child_query)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
print(response.rows)

パラメータ

検索リクエスト

search メソッドには、次のパラメータが含まれます。

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

クエリ設定

search_query は SearchQuery 型で、次のパラメータが含まれます。

名前	型	説明
query (必須)	`Query`	Object フィールドの場合は子フィールドの型に適したクエリを指定します。Nested フィールドの場合は `NestedQuery` を指定します。
sort (任意)	`Sort`	結果のソート順。詳細については、「結果のソートとページネーション」をご参照ください。
get_total_count (任意)	`bool`	一致した行の総数を返すかどうかを指定します。デフォルト値： `False`。このパラメータを `True` に設定すると、クエリのオーバーヘッドが増加します。
next_token (任意)	`bytes`	ページネーショントークン。前回のレスポンスの `next_token` を渡すと、次のページを取得できます。
offset (任意)	`int`	クエリを開始するオフセット。簡易的なページネーションに使用します。
limit (任意)	`int`	返す行の最大数。このパラメータを `0` に設定すると、行は返されません。
aggs (任意)	`list[Agg]`	メトリック集約の設定。詳細については、「集約」をご参照ください。
group_bys (任意)	`list[BaseGroupBy]`	グループ化の設定。詳細については、「集約」をご参照ください。
collapse_field (任意)	`Collapse`	結果の折りたたみ設定。詳細については、「クエリ結果の折りたたみ」をご参照ください。
highlight (任意)	`Highlight`	`Text` フィールドのサマリーおよびハイライトの設定。詳細については、「サマリーとハイライト」をご参照ください。

返される列

columns_to_get は ColumnsToGet 型で、次のパラメータが含まれます。

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

レスポンス

search メソッドは SearchResponse を返します。次の表に主要なフィールドを示します。

フィールド	型	説明
rows	`list[Row]`	クエリによって返される行。件数は `limit` を超えません。
next_token	`bytes`	次ページのトークン。空の値は、これ以上データがないことを示します。
total_count	`int`	一致した行数。この値は `get_total_count` の設定に依存します。
is_all_succeed	`bool`	すべてのインデックスパーティションがクエリされたかどうかを示します。値が `False` の場合、部分的な結果が返されます。
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()