Table Store Java SDK JSON 查詢 - 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` 可能小於實際匹配行數。