表格存储 Python SDK 嵌套类型查询-表格存储 Tablestore(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)