ネステッドクエリ - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

前提条件

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

概要

ネステッドクエリは、Nested 型フィールド内の子の行をクエリします。各子の行は、そのフィールド間のリレーションシップを維持します。子のフィールドを直接クエリすることはできず、子のクエリを NestedQuery でラップする必要があります。path パラメーターは Nested 型フィールドのパスを指定し、子のクエリ内のフィールドはフルパスを使用する必要があります。子のクエリは、任意のクエリタイプを使用できます。同じ子の行で複数の条件を満たす必要がある場合は、それらの条件を 1 つの NestedQuery の子クエリとして含む BoolQuery を使用します。異なる子の行が異なる条件を満たすことができる場合は、条件ごとに 1 つの NestedQuery を作成し、それらを外部の BoolQuery で結合します。

NestedQuery(path, query, score_mode=ScoreMode.NONE, inner_hits=None, weight=None)

次の例では、items Nested 型フィールドの同じ子の行で、items.name が alice と等しく、items.age が 40 未満の行をクエリします。

child_query = BoolQuery(
    must_queries=[
        TermQuery("items.name", "alice"),
        RangeQuery("items.age", range_to=40),
    ]
)
query = NestedQuery("items", child_query)
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 (必須)	`Query`	クエリ条件。このパラメーターを `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`	結果の折りたたみ設定。指定されたフィールドに基づいて重複する結果を削除します。詳細については、「クエリ結果の折りたたみ」をご参照ください。

クエリ条件

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

名前	タイプ	説明
path (必須)	`str`	Nested 型フィールドのパス。多階層の Nested 型フィールドの場合は、`items.details` のようにフルパスを指定します。
query (必須)	`Query`	`path` の子の行で実行するクエリ条件。任意のクエリタイプを使用できます。子のフィールドは `items.name` のようにフルパスを使用する必要があります。
score_mode (任意)	`ScoreMode`	複数の子の行が一致した場合に、親の行のスコアを計算するメソッド。`NONE` (デフォルト) は関連性スコアを計算しません。`AVG`、`MAX`、`MIN`、`TOTAL` は、子の行のスコアの平均値、最大値、最小値、合計値を使用します。
inner_hits (任意)	`InnerHits`	一致した子の行 (インナーヒット) の取得、ソート、ページ分割、ハイライトの設定。このパラメーターが指定されていない場合、一致した子の行の詳細は返されません。
weight (任意)	`float`	クエリ条件の関連性の重み。値は正の浮動小数点数である必要があります。デフォルト値： `1.0`。

一致する子の行

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

名前	タイプ	説明
sort (任意)	`Sort`	一致した子の行のソート順。ソートが不要な場合は、このパラメーターを `None` に設定します。
offset (任意)	`int`	一致した子の行を返す際のオフセット。値を指定しない場合は `None` を渡します。
limit (任意)	`int`	返す一致した子の行の数。`None` を渡した場合、サーバーはデフォルトで 3 つの子の行を返します。
highlight (任意)	`Highlight`	子のフィールドのサマリーとハイライトの設定。ハイライトが不要な場合は、このパラメーターを `None` に設定します。詳細については、「サマリーとハイライト」をご参照ください。

返す列

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	`bytes`	次のページのトークン。このフィールドが空でない場合は、次のリクエストに渡して読み取りを続行します。
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()

例

一致する子の行とハイライトの取得

次の例では、items.name が alice に等しいネストされた子の行をクエリし、一致する子の行とハイライトされたフラグメントを返します。ハイライトの結果は search_hits[].search_inner_hits[].search_hits[].highlight_result で利用できます。

highlight = Highlight([HighlightParameter("items.name")])
inner_hits = InnerHits(
    sort=None,
    offset=0,
    limit=10,
    highlight=highlight,
)
query = NestedQuery(
    "items",
    TermQuery("items.name", "alice"),
    inner_hits=inner_hits,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
for search_hit in response.search_hits:
    for inner_hit in search_hit.search_inner_hits:
        for child_hit in inner_hit.search_hits:
            print(child_hit.row)
            print(child_hit.highlight_result.highlight_fields)