Table Store Java SDK 多條件組合查詢 - Tablestore

前提條件

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

功能說明

多條件組合查詢使用 BoolQuery 將一個或多個子查詢組合成複雜查詢條件。子查詢可以是任意 Query 類型，也可以是另一個 BoolQuery。

BoolQuery 支援以下組合方式：

mustQueries：資料必須滿足所有子查詢，匹配的子查詢參與相關性算分，相當於 AND。
filterQueries：資料必須滿足所有子查詢，但匹配的子查詢不參與相關性算分，也相當於 AND。
shouldQueries：資料必須滿足不低於 minShouldMatch 指定數量的子查詢。滿足的子查詢越多，相關性得分越高，相當於 OR。
mustNotQueries：資料不能滿足其中任何一個子查詢，相當於 NOT，且不參與相關性算分。

未設定 minShouldMatch 時，如果同級只包含 shouldQueries 和 mustNotQueries，則預設至少滿足一個 shouldQueries 子查詢；如果同級包含 mustQueries 或 filterQueries，則 shouldQueries 預設不作為必須滿足的條件。

調用 search 方法執行多條件組合查詢。

SearchResponse search(SearchRequest request)

以下樣本查詢 city 等於 hangzhou 且 category 等於 book 的資料，返回最多 10 行資料及匹配總行數。

String tableName = "example_table";
String indexName = "example_index";
TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(Arrays.asList(cityQuery, categoryQuery));

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

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

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	查詢條件。多條件組合查詢設定為 `BoolQuery`。
offset（可選）	Integer	本次查詢的起始位置。
limit（可選）	Integer	本次查詢返回的最大行數。設定為 `0` 時不返回具體行。
highlight（可選）	Highlight	子查詢匹配 Text 欄位時的摘要與高亮配置。有關配置方法，請參見摘要與高亮。
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 的類型為 BoolQuery，包含以下參數。

名稱	類型	說明
mustQueries（可選）	`List<Query>`	必須全部滿足的子查詢列表。匹配的子查詢參與相關性算分，相當於 AND。
filterQueries（可選）	`List<Query>`	必須全部滿足的子查詢列表。匹配的子查詢不參與相關性算分，相當於 AND。
shouldQueries（可選）	`List<Query>`	至少滿足指定數量的子查詢列表，相當於 OR。滿足的子查詢越多，相關性得分越高。
mustNotQueries（可選）	`List<Query>`	不能滿足其中任何一個條件的子查詢列表，相當於 NOT，且不參與相關性算分。
minShouldMatch（可選）	String 或 int	必須滿足的 `shouldQueries` 子查詢最小數量。可設定整數，例如 `2`，也可設定百分比字串，例如 `"75%"`。未設定時，如果同級包含 `mustQueries` 或 `filterQueries`，預設值為 `0`；其他包含 `shouldQueries` 的情況預設值為 `1`。
weight（可選）	Float	組合查詢權重。未設定時按 `1.0` 處理。值越大，`mustQueries` 和 `shouldQueries` 對最終相關性得分的貢獻越大，不改變匹配範圍。

說明

setMinimumShouldMatch(Integer) 已棄用。請使用 setMinShouldMatch(int) 或 setMinShouldMatch(String)。

返回列

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()` 擷取。可從該欄位讀取相關性得分和摘要與高亮結果。
nextToken	byte[]	下一頁憑證，通過 `getNextToken()` 擷取。值不為 `null` 時，將其設定到下一次請求的 `token` 中繼續讀取。
isAllSuccess	boolean	是否已成功查詢全部索引分割區，通過 `isAllSuccess()` 擷取。值為 `false` 時，返回的是部分結果，`totalCount` 可能小於實際匹配行數。

查詢命中

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

名稱	類型	說明
row	Row	命中的行資料，通過 `getRow()` 擷取。
score	Double	相關性得分，通過 `getScore()` 擷取。使用 `ScoreSort` 按相關性得分排序時返回實際得分。
highlightResultItem	HighlightResultItem	摘要與高亮結果，通過 `getHighlightResultItem()` 擷取。

情境樣本

滿足任意一個條件

使用 shouldQueries 組合多個條件，並通過 minShouldMatch 指定至少滿足的條件數。以下樣本查詢 city 等於 hangzhou 或 category 等於 book 的資料。

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

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(cityQuery, categoryQuery));
boolQuery.setMinShouldMatch(1);

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

排除滿足指定條件的資料

使用 mustNotQueries 排除滿足任一指定條件的資料。以下樣本查詢 city 不等於 hangzhou 的資料。

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

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustNotQueries(Collections.singletonList(cityQuery));

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

過濾多個條件但不參與相關性算分

使用 filterQueries 要求資料滿足所有子查詢，但不讓這些條件參與相關性算分。以下樣本查詢 city 等於 hangzhou 且 category 等於 book 的資料。

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

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setFilterQueries(Arrays.asList(cityQuery, categoryQuery));

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

嵌套組合多個條件

將 BoolQuery 作為另一個 BoolQuery 的子查詢，可表達多層邏輯。以下樣本實現 (city = "hangzhou" OR price < 150) OR (category = "book" AND (price = 300 OR price = 400))。

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

RangeQuery lowPriceQuery = new RangeQuery();
lowPriceQuery.setFieldName("price");
lowPriceQuery.lessThan(ColumnValue.fromLong(150));

BoolQuery firstGroup = new BoolQuery();
firstGroup.setShouldQueries(Arrays.asList(cityQuery, lowPriceQuery));

TermQuery price300Query = new TermQuery();
price300Query.setFieldName("price");
price300Query.setTerm(ColumnValue.fromLong(300));

TermQuery price400Query = new TermQuery();
price400Query.setFieldName("price");
price400Query.setTerm(ColumnValue.fromLong(400));

BoolQuery priceGroup = new BoolQuery();
priceGroup.setShouldQueries(Arrays.asList(price300Query, price400Query));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery secondGroup = new BoolQuery();
secondGroup.setMustQueries(Arrays.asList(categoryQuery, priceGroup));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(firstGroup, secondGroup));

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