Table Store Python SDK 排序和翻頁 - Tablestore

使用 Tablestore Python SDK 查詢多元索引時，可控制結果順序並通過 offset 或 next_token 翻頁。

前提條件

功能說明

多元索引支援索引預排序和查詢時排序。建立多元索引時可通過 index_sort 設定預設返回順序；未設定時預設按主鍵排序。索引預排序只支援 PrimaryKeySort 和 FieldSort，包含 Nested 欄位的多元索引不支援索引預排序；建立後可通過動態修改 Schema 修改索引預排序。查詢時可通過 SearchQuery.sort 設定 ScoreSort、PrimaryKeySort、FieldSort 或 GeoDistanceSort，也可按列表順序組合多個排序器。除主鍵外，排序欄位必須在建立索引時啟用排序與統計彙總。

翻頁方式	說明
limit 和 offset	適用於結果不超過 100,000 行且需要跳到指定位置的情境。`limit + offset` 不能超過 `100000`。
next_token	適用於深度翻頁或順序讀取全部結果。翻頁深度不受 100,000 行限制，但只能順序讀取。

以下樣本先按 score 欄位降序，再按主鍵升序返回前 10 行。

sort = Sort([
    FieldSort("score", SortOrder.DESC),
    PrimaryKeySort(SortOrder.ASC),
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
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`	查詢條件。
sort（可選）	`Sort`	查詢時排序配置。未設定時使用索引預排序。使用 `next_token` 翻頁時不再設定。
offset（可選）	`int`	起始位置，預設值為 `0`。使用 `next_token` 翻頁時不能設定。
limit（可選）	`int`	最大返回行數，預設值為 `10`。從資料表讀取任一返回列時最大值為 `100`；只從多元索引讀取返回列時最大值為 `1000`。
next_token（可選）	`bytes`	翻頁憑證。首次請求不設定；後續請求使用上一次響應的 `next_token`。
get_total_count（可選）	`bool`	是否返回匹配總行數。預設值為 `False`。

排序配置

search_query.sort 的類型為 Sort，包含以下參數。

名稱	類型	說明
sorters（必選）	`list[Sorter]`	排序器列表。列表順序決定多級排序優先順序，支援 `ScoreSort`、`PrimaryKeySort`、`FieldSort` 和 `GeoDistanceSort`。

主鍵排序

search_query.sort.sorters[] 設定為 PrimaryKeySort 時，按照主鍵排序，包含以下參數。

名稱	類型	說明
sort_order（可選）	`SortOrder`	排序方向，預設值為 `ASC`。

欄位排序

search_query.sort.sorters[] 設定為 FieldSort 時，按照欄位值排序，包含以下參數。

名稱	類型	說明
field_name（必選）	`str`	排序欄位名稱，欄位必須啟用排序與統計彙總。
sort_order（可選）	`SortOrder`	排序方向，預設值為 `ASC`。
sort_mode（可選）	`SortMode`	多重值欄位的取值方式：`MIN`、`MAX` 或 `AVG`。
nested_filter（可選）	`NestedFilter`	Nested 子欄位排序配置，包含 Nested 路徑和篩選參與排序子行的查詢條件。

地理距離排序

search_query.sort.sorters[] 設定為 GeoDistanceSort 時，按照地理點與目標點之間的距離排序，包含以下參數。

名稱	類型	說明
field_name（必選）	`str`	GeoPoint 類型排序欄位名稱。
points（必選）	`list[str]`	目標地理點列表，使用 `緯度,經度` 格式。
sort_order（可選）	`SortOrder`	`ASC` 表示由近到遠，`DESC` 表示由遠到近。
sort_mode（可選）	`SortMode`	存在多個距離時的取值方式：`MIN`、`MAX` 或 `AVG`。
geo_distance_type（可選）	`GeoDistanceType`	距離計算方式。`ARC`（預設）按球面計算；`PLANE` 按平面計算。
nested_filter（可選）	`NestedFilter`	Nested 子欄位排序配置。

返回列

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

next_token 為空白也可能表示當前查詢沒有確定的排序方式。total_count 是匹配總行數，不是本頁行數。

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

情境樣本

按地理距離排序

以下樣本按 location 與 30.25,120.16 的球面距離由近到遠返回結果。

sort = Sort([
    GeoDistanceSort(
        "location",
        ["30.25,120.16"],
        sort_order=SortOrder.ASC,
        sort_mode=SortMode.MIN,
        geo_distance_type=GeoDistanceType.ARC,
    )
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
)
print(response.rows)

使用 next_token 翻頁

首次請求設定排序方式，後續請求只傳入上一次響應的 next_token 和相同的查詢條件，直到憑證為空白。

query = MatchAllQuery()
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, sort=Sort([PrimaryKeySort()]), limit=100),
)
all_rows = list(response.rows)

while response.next_token:
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(query, next_token=response.next_token, limit=100),
    )
    all_rows.extend(response.rows)

print(len(all_rows))

重要

使用 next_token 翻頁時不能設定 offset，也不能直接跳頁。需要向前翻頁時，可緩衝各頁請求所用的 next_token，並使用目標頁對應的憑證重新查詢。包含 Nested 欄位的多元索引沒有索引預排序，首次查詢必須顯式設定 sort，否則服務端不返回 next_token。

Tablestore：排序和翻頁