Table Store Python SDK JSON 查詢 - Tablestore

前提條件

多元索引已將目標欄位配置為 JSON 類型，並設定為 Object 或 Nested。有關配置方法，請參見建立多元索引。

功能說明

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。有關其他配置，請參見巢狀型別查詢。

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]`	查詢命中結果，包含行資料、相關性得分和高亮結果等擴充資訊。

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