Table Store Java SDK 查詢後過濾 - Tablestore

前提條件

安裝Tablestore Java SDK並初始化用戶端。
使用 5.17.5 及以上版本的 Tablestore Java SDK。

功能說明

查詢後過濾（SearchFilter）在主查詢（query）完成後對候選資料進行二次篩選，篩選結果再參與統計彙總和分組。將適合後置執行的條件配置為查詢後過濾條件，可減少複雜條件在主查詢階段的計算開銷；是否能改善效能取決於主查詢篩選效果和過濾條件。

調用 search 方法時，在 SearchQuery 中分別設定主查詢條件和 SearchFilter。主查詢可使用多元索引支援的查詢類型；查詢後過濾條件僅支援特定查詢類型和欄位，具體限制請參見使用限制。

SearchResponse search(SearchRequest request)

以下樣本先通過 TermsQuery 查詢 category 欄位值為 book 的資料，再通過查詢後過濾保留 score_long 欄位值大於 1 且小於 10 的資料。

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

// 設定主查詢條件。
TermsQuery termsQuery = new TermsQuery();
termsQuery.setFieldName("category");
termsQuery.addTerm(ColumnValue.fromString("book"));

// 設定查詢後過濾條件。
RangeQuery rangeQuery = new RangeQuery();
rangeQuery.setFieldName("score_long");
rangeQuery.setFrom(ColumnValue.fromLong(1));
rangeQuery.setIncludeLower(false);
rangeQuery.setTo(ColumnValue.fromLong(10));
rangeQuery.setIncludeUpper(false);

SearchFilter searchFilter = new SearchFilter();
searchFilter.setQuery(rangeQuery);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(termsQuery);
searchQuery.setFilter(searchFilter);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

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

SearchResponse response = client.search(request);
System.out.println("Total count: " + response.getTotalCount());
System.out.println("Rows: " + response.getRows());

使用限制

查詢後過濾必須與主查詢條件組合使用。為減少進入查詢後過濾階段的資料量，應通過主查詢儘可能縮小候選資料範圍；除非需要對全部索引資料執行過濾，否則不建議將主查詢設定為 MatchAllQuery。
過濾條件僅支援 TermQuery、TermsQuery、RangeQuery、ExistsQuery，以及由這些查詢類型組成的 BoolQuery。
過濾條件中的 BoolQuery 僅支援 mustQueries、mustNotQueries 和 shouldQueries，不支援 filterQueries。
過濾欄位僅支援 Keyword、Long 和 Double 類型，並且必須啟用 enableSortAndAgg。
過濾條件不參與相關性評分。為過濾條件設定 weight 不會改變查詢結果的相關性得分。

參數說明

查詢請求

request 的類型為 SearchRequest，包含以下參數。

名稱	類型	說明
tableName（必選）	String	資料表名稱。
indexName（必選）	String	多元索引名稱。
searchQuery（必選）	SearchQuery	主查詢條件、查詢後過濾條件和通用查詢配置。
columnsToGet（可選）	SearchRequest.ColumnsToGet	返回列配置。未設定時只返回主鍵列。
timeoutInMillisecond（可選）	int	請求級查詢逾時時間，單位為毫秒。預設值為 `-1`，表示不單獨設定查詢逾時時間。
routingValues（可選）	`List<PrimaryKey>`	自訂路由欄位對應的主索引值列表。未配置自訂路由時無需設定。

查詢配置

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

名稱	類型	說明
query（必選）	Query	主查詢條件。支援多元索引的查詢類型。
filter（必選）	SearchFilter	查詢後過濾配置，在主查詢完成後進一步篩選候選資料。
offset（可選）	Integer	本次查詢的起始位置。
limit（可選）	Integer	本次查詢返回的最大行數。設定為 `0` 時不返回具體行。
highlight（可選）	Highlight	`Text` 欄位的摘要與高亮配置。有關配置方法，請參見摘要與高亮。
collapse（可選）	Collapse	結果摺疊配置，用於按指定列對返回結果去重。有關配置方法，請參見摺疊（去重）。
sort（可選）	Sort	返回結果的排序方式。有關配置方法，請參見排序和翻頁。
trackTotalCount（可選）	int	期望統計的最大匹配行數。預設值為 `TRACK_TOTAL_COUNT_DISABLED`，表示不統計；設定為 `TRACK_TOTAL_COUNT` 時統計全部匹配行。值越小，查詢效能越高。
aggregationList（可選）	`List<Aggregation>`	統計彙總配置。統計彙總基於查詢後過濾結果執行。有關配置方法，請參見統計彙總。
groupByList（可選）	`List<GroupBy>`	分組配置。分組基於查詢後過濾結果執行。有關配置方法，請參見統計彙總。
token（可選）	byte[]	翻頁憑證。將上一次響應的 `nextToken` 設定為該參數可繼續讀取後續資料。設定 `token` 時，SDK 會清除 `sort`，因為翻頁憑證中已包含排序條件。

查詢後過濾配置

request.searchQuery.filter 的類型為 SearchFilter，包含以下參數。

名稱	類型	說明
query（必選）	Query	過濾條件。僅支援 `TermQuery`、`TermsQuery`、`RangeQuery`、`ExistsQuery`，以及由這些查詢類型組成的 `BoolQuery`。

返回列

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()` 擷取。
aggregationResults	AggregationResults	基於查詢後過濾結果計算的統計彙總結果，通過 `getAggregationResults()` 擷取。
groupByResults	GroupByResults	基於查詢後過濾結果計算的分組結果，通過 `getGroupByResults()` 擷取。
nextToken	byte[]	下一頁憑證，通過 `getNextToken()` 擷取。值不為 `null` 時，將其設定到下一次請求的 `token` 中繼續讀取。
isAllSuccess	boolean	是否已成功查詢全部索引分割區，通過 `isAllSuccess()` 擷取。值為 `false` 時，返回的是部分結果，`totalCount` 可能小於實際匹配行數。