表格存储 Java SDK JSON 查询-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Tablestore Java SDK 可查询多元索引中 Object 或 Nested 类型 JSON 字段的子字段；Object 类型不保留子对象边界，Nested 类型保留子对象边界。

前提条件

安装Tablestore Java SDK并初始化客户端。
多元索引已将目标字段配置为 JSON 类型，并通过 jsonType 设置为 OBJECT 或 NESTED。有关配置方法，请参见创建多元索引。

功能说明

JSON 查询没有独立的查询类型。根据多元索引中 JSON 字段的 jsonType 选择查询方式。

JSON 类型	字段关系	查询方式
Object	不保留数组中各子对象的边界。不同查询条件可以由不同子对象分别满足。	直接使用与子字段类型和匹配需求相符的查询类型，子字段名称使用完整路径。
Nested	将数组中的每个子对象作为独立子行，保留同一子对象内各字段的对应关系。	使用 `NestedQuery` 包裹子查询，并通过 `path` 指定 Nested 字段的完整路径。

例如，数据表的 address 列为 String 类型，用于存储以下 JSON 数组：

[
  { "country": "China", "city": "hangzhou" },
  { "country": "usa", "city": "Seattle" }
]

同时查询 country="China" 和 city="Seattle" 时，如果 address 在多元索引中配置为 Object 类型，该行会被命中，因为两个条件可以由不同子对象分别满足；如果配置为 Nested 类型，该行不会被命中，因为没有一个子对象同时满足两个条件。

调用 search 方法执行 JSON 查询。

SearchResponse search(SearchRequest request)

说明

JSON 字段的 subFieldSchemas 不支持 Vector 类型子字段。

查询 Object 字段

以下示例查询 address.country 等于 China，且 address.city 等于 Seattle 的行。由于 address 为 Object 类型，两个条件可以由不同子对象分别满足。

String tableName = "example_table";
String indexName = "example_index";

TermQuery countryQuery = new TermQuery();
countryQuery.setFieldName("address.country");
countryQuery.setTerm(ColumnValue.fromString("China"));

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("address.city");
cityQuery.setTerm(ColumnValue.fromString("Seattle"));

BoolQuery objectQuery = new BoolQuery();
objectQuery.setMustQueries(Arrays.asList(countryQuery, cityQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(objectQuery);
searchQuery.setLimit(10);

SearchRequest request =
        new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
System.out.println(response.getRows());

查询 Nested 字段

以下示例查询 address 中同一个子对象的 address.country 等于 China，且 address.city 等于 Seattle 的行。有关 Nested 类型的其他查询方式和参数，请参见嵌套类型查询。

String tableName = "example_table";
String indexName = "example_index";

TermQuery countryQuery = new TermQuery();
countryQuery.setFieldName("address.country");
countryQuery.setTerm(ColumnValue.fromString("China"));

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("address.city");
cityQuery.setTerm(ColumnValue.fromString("Seattle"));

BoolQuery childQuery = new BoolQuery();
childQuery.setMustQueries(Arrays.asList(countryQuery, cityQuery));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("address");
nestedQuery.setQuery(childQuery);
nestedQuery.setScoreMode(ScoreMode.None);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(nestedQuery);
searchQuery.setLimit(10);

SearchRequest request =
        new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
System.out.println(response.getRows());

参数说明

查询请求

request 的类型为 SearchRequest，包含以下参数。

名称	类型	说明
tableName（必选）	String	数据表名称。
indexName（必选）	String	多元索引名称。
searchQuery（必选）	SearchQuery	查询条件和通用查询配置。
columnsToGet（可选）	SearchRequest.ColumnsToGet	返回列配置。未设置时只返回主键列。
timeoutInMillisecond（可选）	int	请求级查询超时时间，单位为毫秒。默认值为 `-1`，表示不单独设置查询超时时间。
routingValues（可选）	`List<PrimaryKey>`	自定义路由字段对应的主键值列表。未配置自定义路由时无需设置。

查询配置

request.searchQuery 的类型为 SearchQuery，包含以下参数。

名称	类型	说明
query（必选）	Query	查询条件。查询 Object 类型字段时，直接设置与子字段类型和匹配需求相符的查询类型；查询 Nested 类型字段时，设置为 `NestedQuery`。
offset（可选）	Integer	本次查询的起始位置。
limit（可选）	Integer	本次查询返回的最大行数。设置为 `0` 时不返回具体行。
highlight（可选）	Highlight	摘要与高亮配置。Nested 类型字段通过 `NestedQuery.innerHits` 配置匹配子行的摘要与高亮。
collapse（可选）	Collapse	结果折叠配置，用于按指定列对返回结果去重。
sort（可选）	Sort	返回结果的排序方式。
trackTotalCount（可选）	int	期望统计的最大匹配行数。默认值为 `TRACK_TOTAL_COUNT_DISABLED`，表示不统计；设置为 `TRACK_TOTAL_COUNT` 时统计全部匹配行。值越小，查询性能越高。
filter（可选）	SearchFilter	对 `query` 的查询结果进行过滤。
aggregationList（可选）	`List<Aggregation>`	统计聚合配置。
groupByList（可选）	`List<GroupBy>`	分组配置。
token（可选）	byte[]	翻页凭证。将上一次响应的 `nextToken` 设置为该参数可继续读取后续数据。设置 `token` 时，SDK 会清除 `sort`，因为翻页凭证中已包含排序条件。

嵌套查询条件

查询 Nested 类型字段时，request.searchQuery.query 的类型为 NestedQuery，包含以下参数。

名称	类型	说明
path（必选）	String	要查询的 Nested 字段路径。查询多层 Nested 字段时，设置为目标字段的完整路径。
query（必选）	Query	在 `path` 对应子行中执行的查询条件。子字段名称需要使用完整路径。
scoreMode（必选）	ScoreMode	多个子行匹配时的父行评分方式。`None` 不计算子行相关性得分；`Avg`、`Max`、`Min` 和 `Total` 分别使用子行得分的平均值、最大值、最小值和总和。
innerHits（可选）	InnerHits	匹配子行的返回、排序、分页和高亮配置。未设置时不返回匹配子行的明细。
weight（可选）	float	查询权重，默认值为 `1.0`，取值为正浮点数。值越大，匹配行的得分越高；该参数不改变匹配范围。

子行返回配置

request.searchQuery.query.innerHits 的类型为 InnerHits，包含以下参数。

名称	类型	说明
sort（可选）	Sort	匹配子行的排序方式。可使用 `ScoreSort` 和 `DocSort`，不支持 `FieldSort`。
offset（可选）	Integer	返回匹配子行的起始位置。
limit（可选）	Integer	返回匹配子行的最大数量，默认值为 `3`。
highlight（可选）	Highlight	匹配子行的摘要与高亮配置。

返回列

request.columnsToGet 的类型为 SearchRequest.ColumnsToGet，包含以下参数。

名称	类型	说明
columns（可选）	`List<String>`	要返回的属性列名称。仅 `returnAll` 和 `returnAllFromIndex` 均为 `false` 时需要设置；未设置时只返回主键列。
returnAll（可选）	boolean	是否返回数据表中的全部属性列。默认值为 `false`。
returnAllFromIndex（可选）	boolean	是否返回已建立索引的全部属性列。默认值为 `false`。不能与 `returnAll` 同时设置为 `true`。

返回值

search 方法返回 SearchResponse，核心字段如下。

名称	类型	说明
totalCount	long	匹配行数，通过 `getTotalCount()` 获取。返回值取决于 `trackTotalCount` 配置。
rows	`List<Row>`	本次查询返回的行数据，通过 `getRows()` 获取。返回数量不超过 `limit`。
searchHits	`List<SearchHit>`	查询命中结果，通过 `getSearchHits()` 获取。可从该字段读取命中行、得分、摘要与高亮结果和 Nested 类型字段的匹配子行。
nextToken	byte[]	下一页凭证，通过 `getNextToken()` 获取。值不为 `null` 时，将其设置到下一次请求的 `token` 中继续读取。
isAllSuccess	boolean	是否已成功查询全部索引分区，通过 `isAllSuccess()` 获取。值为 `false` 时返回部分结果，`totalCount` 可能小于实际匹配行数。