Table Store Java SDK 巢狀型別查詢 - Tablestore

前提條件

安裝Tablestore Java SDK並初始化用戶端。

功能說明

巢狀型別查詢用於查詢 Nested 類型欄位中的子行。Nested 欄位的每個子行獨立保留欄位間的對應關係，不能直接按其子欄位查詢，需要使用 NestedQuery 包裹子查詢。

NestedQuery.path 指定要查詢的嵌套欄位路徑，子查詢中的欄位名稱需要使用完整路徑。子查詢可以是任意 Query 類型。多層嵌套欄位可以直接將 path 設定為目標嵌套欄位的完整路徑，也可以使用多層 NestedQuery 逐層查詢。

多個條件是否必須由同一個子行滿足，取決於 NestedQuery 與 BoolQuery 的組合方式：

同一個子行必須滿足多個條件時，將包含多個子條件的 BoolQuery 設定為一個 NestedQuery 的子查詢。
不同子行可以分別滿足多個條件時，為每個條件分別構造 NestedQuery，再使用外層 BoolQuery 組合。

調用 search 方法執行巢狀型別查詢。查詢條件需要指定嵌套欄位路徑、子查詢和評分模式。

SearchResponse search(SearchRequest request)

以下樣本查詢 items 嵌套欄位中，items.keyword 等於 tablestore 的子行，返回最多 10 行資料及匹配總行數。

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

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(termQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
System.out.println(response.getTotalCount());
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	查詢條件。巢狀型別查詢設定為 `NestedQuery`。
offset（可選）	Integer	本次查詢的起始位置。
limit（可選）	Integer	本次查詢返回的最大行數。設定為 `0` 時不返回具體行。
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`，因為翻頁憑證中已包含排序條件。

巢狀查詢條件

request.searchQuery.query 的類型為 NestedQuery，包含以下參數。

名稱	類型	說明
path（必選）	String	要查詢的嵌套欄位路徑。查詢多層嵌套欄位時，設定為目標嵌套欄位的完整路徑，例如 `items.details`。
query（必選）	Query	在 `path` 對應的子行中執行的查詢條件，可以是任意 `Query` 類型。子欄位名稱需要使用完整路徑，例如 `items.keyword`。
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()` 擷取。設定 `innerHits` 後，從該欄位讀取匹配子行。
nextToken	byte[]	下一頁憑證，通過 `getNextToken()` 擷取。值不為 `null` 時，將其設定到下一次請求的 `token` 中繼續讀取。
isAllSuccess	boolean	是否已成功查詢全部索引分割區，通過 `isAllSuccess()` 擷取。值為 `false` 時，返回的是部分結果，`totalCount` 可能小於實際匹配行數。

查詢命中

response.searchHits[] 的類型為 SearchHit，包含以下核心欄位。

名稱	類型	說明
row	Row	命中的行或子行資料，通過 `getRow()` 擷取。
score	Double	相關性得分，通過 `getScore()` 擷取。
offset	Integer	嵌套子行在原數組中的位置，通過 `getOffset()` 擷取。父行命中結果中該欄位可能為空白。
highlightResultItem	HighlightResultItem	高亮結果，通過 `getHighlightResultItem()` 擷取。
searchInnerHits	`Map<String, SearchInnerHit>`	按嵌套欄位路徑組織的匹配子行，通過 `getSearchInnerHits()` 擷取；也可以通過 `getSearchInnerHitByPath(path)` 擷取指定路徑的結果。

嵌套命中

response.searchHits[].searchInnerHits 的實值型別為 SearchInnerHit，包含以下欄位。

名稱	類型	說明
path	String	嵌套欄位路徑，通過 `getPath()` 擷取。
subSearchHits	`List<SearchHit>`	匹配的子行，通過 `getSubSearchHits()` 擷取。多層巢狀查詢中，子行的 `searchInnerHits` 可繼續包含下一層匹配結果。

情境樣本

查詢多層嵌套欄位

查詢多層嵌套欄位時，將 path 設定為目標嵌套欄位的完整路徑，並在子查詢中指定子欄位的完整路徑。以下樣本查詢 items.details.name 等於 beta 的資料。

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.details.name");
termQuery.setTerm(ColumnValue.fromString("beta"));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items.details");
nestedQuery.setQuery(termQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

同一子行滿足多個條件

將包含多個子條件的 BoolQuery 設定為一個 NestedQuery 的子查詢。以下樣本要求 items 中存在同一個子行，同時滿足 items.keyword 等於 tablestore 且 items.number 存在。

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.number");

BoolQuery childQuery = new BoolQuery();
childQuery.setMustQueries(Arrays.asList(termQuery, existsQuery));

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

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

不同子行滿足多個條件

為每個條件分別構造 NestedQuery，再使用外層 BoolQuery 組合。以下樣本允許 items.keyword 等於 tablestore 和 items.number 存在兩個條件由不同子行分別滿足。

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));
NestedQuery termNestedQuery = new NestedQuery();
termNestedQuery.setPath("items");
termNestedQuery.setQuery(termQuery);
termNestedQuery.setScoreMode(ScoreMode.None);

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.number");
NestedQuery existsNestedQuery = new NestedQuery();
existsNestedQuery.setPath("items");
existsNestedQuery.setQuery(existsQuery);
existsNestedQuery.setScoreMode(ScoreMode.None);

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(
        Arrays.asList(termNestedQuery, existsNestedQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

返回並高亮匹配的子行

通過 InnerHits 配置匹配子行的返回數量、排序和高亮。以下樣本查詢 items.description 中包含 hangzhou 的子行，並返回高亮結果。

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("items.description");
matchQuery.setText("hangzhou");

HighlightParameter parameter = new HighlightParameter();
parameter.setPreTag("<em>");
parameter.setPostTag("</em>");
Highlight highlight = new Highlight();
highlight.addFieldHighlightParam("items.description", parameter);

InnerHits innerHits = new InnerHits();
innerHits.setLimit(3);
innerHits.setSort(new Sort(Arrays.asList(
        new ScoreSort(), new DocSort(SortOrder.ASC))));
innerHits.setHighlight(highlight);

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(matchQuery);
nestedQuery.setScoreMode(ScoreMode.None);
nestedQuery.setInnerHits(innerHits);

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

多層巢狀查詢需要在哪一層返回或高亮匹配子行，就在對應層的 NestedQuery 中分別設定 innerHits。