Table Store Python SDK 巢狀型別查詢 - Tablestore

前提條件

功能說明

巢狀型別查詢用於查詢 Nested 欄位中的子行。Nested 欄位的每個子行獨立保留欄位間的對應關係，不能直接按其子欄位查詢，需要使用 NestedQuery 包裹子查詢。path 指定嵌套欄位路徑，子查詢中的欄位名稱需要使用完整路徑。子查詢可以是任意 Query 類型。同一個子行必須滿足多個條件時，將包含多個子條件的 BoolQuery 設定為一個 NestedQuery 的子查詢；不同子行可以分別滿足多個條件時，為每個條件分別構造 NestedQuery，再使用外層 BoolQuery 組合。

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

以下樣本查詢 items 嵌套欄位中，同一個子行的 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`	要查詢的嵌套欄位路徑。查詢多層嵌套欄位時，設定為目標欄位的完整路徑，例如 `items.details`。
query（必選）	`Query`	在 `path` 對應子行中執行的查詢條件，可以是任意 Query 類型。子欄位名稱需要使用完整路徑，例如 `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]`	查詢命中結果，包含相關性評分、高亮結果和匹配子行等擴充資訊。

相容 Tuple 返回格式

Tablestore Python SDK 5.2.0 開始將查詢介面的傳回值由 Tuple 調整為響應對象，5.1.0 及以下版本直接返回 Tuple。5.2.1 及以上版本可調用 SearchResponse.v1_response() 擷取與舊版本相容的 Tuple。新代碼建議直接存取 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)