表格存储 Go SDK 排序和翻页-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Tablestore Go SDK 按字段值、相关性评分、主键或地理距离排序查询结果，并通过 Token 连续翻页。

前提条件

安装Tablestore Go SDK并初始化客户端。

功能说明

查询时可以设置一个或多个排序器，系统按排序器列表的先后顺序比较结果。未设置排序时使用创建多元索引时配置的 IndexSort；未配置 IndexSort 时默认按主键排序。IndexSort 仅支持 PrimaryKeySort 和 FieldSort。创建索引后，可通过动态修改 Schema修改 IndexSort。ScoreSort 按 BM25 算法计算的相关性评分排序，必须显式设置才会生效。

重要

查询时指定非主键排序器后，服务端默认追加主键排序器，使排序值相同的行保持确定的返回顺序。DisableDefaultPkSorter 的默认值为 false。使用 Token 翻页时不要禁用该行为；如果排序值重复且禁用主键排序，可能漏读数据。
包含 Nested 字段的多元索引不支持 IndexSort。如果查询此类索引时需要翻页，必须在查询请求中显式设置排序，否则数据未读取完时服务端不会返回 NextToken。
使用 ScoreSort 时，FuzzyKeyword 字段不参与排序，且 Weight 对 FuzzyKeyword 字段无效。

searchQuery := search.NewSearchQuery().
    SetQuery(&search.MatchAllQuery{}).
    SetLimit(10).
    SetSort(&search.Sort{Sorters: []search.Sorter{
        &search.FieldSort{
            FieldName: "price",
            Order:     search.SortOrder_DESC.Enum(),
        },
    }})

for {
    response, err := client.Search(&tablestore.SearchRequest{
        TableName:   "example_table",
        IndexName:   "example_index",
        SearchQuery: searchQuery,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, row := range response.Rows {
        fmt.Println(row)
    }
    if len(response.NextToken) == 0 {
        break
    }
    searchQuery.SetToken(response.NextToken)
}

参数说明

排序配置

名称	类型	说明
Sorters（必选）	[]search.Sorter	排序器列表，支持 FieldSort、ScoreSort、PrimaryKeySort 和 GeoDistanceSort。排序器按列表顺序依次生效。DocSort 仅支持在 NestedQuery.InnerHits 中显式设置，不能作为顶层 Search 的排序器。
DisableDefaultPkSorter（可选）	*bool	是否禁用服务端自动追加的主键排序器，默认值为 false。Go SDK 1.7.16 及以上版本支持该参数。

字段值排序

名称	类型	说明
FieldName（必选）	string	用于排序的字段名称。该字段必须启用排序与统计聚合。
Order（可选）	*search.SortOrder	排序方向，支持 search.SortOrder_ASC 和 search.SortOrder_DESC，默认升序。
Mode（可选）	*search.SortMode	多值字段参与排序的取值方式，支持 search.SortMode_Min、search.SortMode_Max 和 search.SortMode_Avg。
NestedFilter（可选）	*search.NestedFilter	Nested 子字段排序配置。仅对 Nested 子字段排序时设置。
MissingValue（可选）	interface{}	FieldName 和 MissingFields 指定的字段均缺失时的排序值。设置为 search.FirstWhenMissing 时，无论升序或降序，缺失值均排在最前；设置为 search.LastWhenMissing 或 nil 时均排在最后。也可以设置与字段类型一致的自定义值参与排序。
MissingField（可选）	*string	备用排序字段。该参数已废弃，请使用 MissingFields。
MissingFields（可选）	[]string	备用排序字段列表。FieldName 指定的字段缺失时，按列表顺序使用首个存在的字段值参与排序。最多设置 3 个，且字段类型必须与 FieldName 指定的字段相同，所有字段都必须启用排序与统计聚合。Go SDK 1.9.0 及以上版本支持该参数。

Nested 过滤

名称	类型	说明
Path（必选）	string	Nested 字段路径。
Filter（必选）	search.Query	筛选参与排序的 Nested 子行的查询条件。设置为 MatchAllQuery 时使用全部子行。

地理距离排序

名称	类型	说明
FieldName（必选）	string	Geo-point 字段名称。
Points（必选）	[]string	用于计算距离的目标点列表。坐标使用 `纬度,经度` 格式，纬度范围为 `[-90,+90]`，经度范围为 `[-180,+180]`，例如 `35.8,-45.91`。
Order（可选）	*search.SortOrder	距离排序方向。search.SortOrder_ASC 表示由近到远，search.SortOrder_DESC 表示由远到近。
Mode（可选）	*search.SortMode	存在多个距离时参与排序的取值方式，支持 search.SortMode_Min、search.SortMode_Max 和 search.SortMode_Avg。
GeoDistanceType（可选）	*search.GeoDistanceType	距离计算方式。search.GeoDistanceType_ARC 按球面计算，精度较高；search.GeoDistanceType_PLANE 按平面计算，计算量较小。默认值为 ARC。
NestedFilter（可选）	*search.NestedFilter	Nested 子字段排序时的路径和过滤条件。

翻页配置

名称	类型	说明
Limit（可选）	int32	每页返回的最大行数，默认值为 10。通常最大值为 100；如果返回列均存储在多元索引中，最大值可提高到 1000，具体请参见如何将多元索引 Search 接口查询数据的 limit 提高到 1000。使用 Offset 翻页时，Offset + Limit 不能超过 100000。
Offset（可选）	int32	起始位置，默认值为 0，适合不超过 100000 行的浅翻页。
Token（可选）	[]byte	上一页响应中的 NextToken，适合连续深度翻页。调用 SetToken 会清除 Sort，因为 Token 已包含上一页的排序条件；使用 Token 翻页时不能设置 Offset。如需将二进制 Token 持久化或通过文本协议、跨进程传输，使用 Base64 编码。

Token 默认只能向后翻页。如需返回上一页，可以缓存之前响应的 Token 并重新使用。Token 翻页深度不受 100000 行限制。

返回值

名称	类型	说明
Rows	[]*tablestore.Row	本次查询返回的行，数量不超过 Limit。
SearchHits	[]*tablestore.SearchHit	查询命中结果。使用相关性评分、摘要与高亮或 Nested InnerHits 时从该字段读取。
TotalCount	int64	匹配总行数。返回值取决于 SetGetTotalCount 配置，不是本页返回行数。
NextToken	[]byte	下一页凭证。值为空表示没有更多数据，或当前查询没有确定的排序方式。
IsAllSuccess	bool	是否已成功查询全部索引分区。值为 false 时返回的是部分结果。

名称	类型	说明
ScoreSort.Order（可选）	*search.SortOrder	BM25 相关性评分的排序方向。search.NewScoreSort() 默认按评分降序排列。
PrimaryKeySort.Order（可选）	*search.SortOrder	主键排序方向。search.NewPrimaryKeySort() 默认按主键升序排列。
DocSort.SortOrder（可选）	*search.SortOrder	NestedQuery.InnerHits 内部文档的排序方向，默认升序。Go SDK 1.7.12 及以上版本支持 DocSort。