表格存储 Python SDK 排序和翻页-表格存储 Tablestore(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。

排序和翻页