表格存储 Python SDK JSON 查询-表格存储 Tablestore(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()