摘要：搜索請求用于與搜索文檔聚合相關(guān)的任何操作，還提供了在結(jié)果文檔上請求高亮的方法。將字段高光色添加到高亮構(gòu)建器。稍后可以從中檢索高亮的文本片段。

SearchRequest用于與搜索文檔、聚合、suggestions相關(guān)的任何操作，還提供了在結(jié)果文檔上請求高亮的方法。

在最基本的表單中，我們可以向請求添加查詢：

SearchRequest searchRequest = new SearchRequest(); 
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); 
searchSourceBuilder.query(QueryBuilders.matchAllQuery()); 
searchRequest.source(searchSourceBuilder); 

創(chuàng)建SeachRequest，沒有參數(shù)，這將針對所有索引運(yùn)行。

大多數(shù)搜索參數(shù)都添加到SearchSourceBuilder中，它為搜索請求body中的所有內(nèi)容提供了setter。

將match_all查詢添加到SearchSourceBuilder。

將SearchSourceBuilder添加到SeachRequest。

我們先來看一下SearchRequest的一些可選參數(shù)：

SearchRequest searchRequest = new SearchRequest("posts");
searchRequest.types("doc");

將請求限制為一個索引。

將請求限制為一個類型。

還有一些其他有趣的可選參數(shù)：

searchRequest.routing("routing");

設(shè)置路由參數(shù)。

searchRequest.indicesOptions(IndicesOptions.lenientExpandOpen());

設(shè)置IndicesOptions控制如何解析不可用的索引以及如何擴(kuò)展通配符表達(dá)式。

searchRequest.preference("_local");

使用首選項參數(shù)，例如執(zhí)行搜索以優(yōu)先選擇本地碎片，默認(rèn)是隨機(jī)的跨碎片。

控制搜索行為的大多數(shù)選項都可以在SearchSourceBuilder上設(shè)置，它包含或多或少與Rest API的搜索請求body中等效的選項。

以下是一些常見選項的幾個示例：

SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); 
sourceBuilder.query(QueryBuilders.termQuery("user", "kimchy")); 
sourceBuilder.from(0); 
sourceBuilder.size(5); 
sourceBuilder.timeout(new TimeValue(60, TimeUnit.SECONDS));

使用默認(rèn)選項創(chuàng)建SearchSourceBuilder。

設(shè)置查詢，可以是任何類型的QueryBuilder。

設(shè)置確定結(jié)果要從哪個索引開始搜索的from選項，默認(rèn)為0。

設(shè)置確定搜索命中返回的數(shù)的size選項，默認(rèn)為10。

設(shè)置一個可選的超時，控制允許搜索的時間。

在此之后，只需將SearchSourceBuilder添加到SearchRequest：

SearchRequest searchRequest = new SearchRequest();
searchRequest.indices("posts");
searchRequest.source(sourceBuilder);

使用QueryBuilder對象創(chuàng)建搜索查詢，QueryBuilder存在對于Elasticsearch的查詢DSL支持的每種搜索查詢類型。

可以使用其構(gòu)造函數(shù)創(chuàng)建QueryBuilder：

MatchQueryBuilder matchQueryBuilder = new MatchQueryBuilder("user", "kimchy");

創(chuàng)建一個在字段“user”上匹配文本“kimchy”的全文匹配查詢。

創(chuàng)建后，QueryBuilder對象提供了配置其創(chuàng)建的搜索查詢選項的方法：

matchQueryBuilder.fuzziness(Fuzziness.AUTO); 
matchQueryBuilder.prefixLength(3); 
matchQueryBuilder.maxExpansions(10); 

在匹配查詢上啟用模糊匹配。

在匹配查詢上設(shè)置前綴長度選項。

設(shè)置最大擴(kuò)展選項以控制查詢的模糊過程。

也可以使用QueryBuilders實用程序類創(chuàng)建QueryBuilder對象，此類提供了可用于使用流暢的編程樣式創(chuàng)建QueryBuilder對象的輔助方法：

QueryBuilder matchQueryBuilder = QueryBuilders.matchQuery("user", "kimchy")
                                                .fuzziness(Fuzziness.AUTO)
                                                .prefixLength(3)
                                                .maxExpansions(10);

無論用于創(chuàng)建它的方法是什么，都必須將QueryBuilder對象添加到SearchSourceBuilder，如下所示：

searchSourceBuilder.query(matchQueryBuilder);

構(gòu)建查詢頁面提供了所有可用的搜索查詢的列表及其相應(yīng)的QueryBuilder對象和QueryBuilders輔助方法。

SearchSourceBuilder允許添加一個或多個SortBuilder實例，有四種特殊的實現(xiàn)（Field-，Score-，GeoDistance-和ScriptSortBuilder）。

sourceBuilder.sort(new ScoreSortBuilder().order(SortOrder.DESC)); 
sourceBuilder.sort(new FieldSortBuilder("_uid").order(SortOrder.ASC));

按_score降序排序（默認(rèn)值）。

也可以按_id字段進(jìn)行升序排序。

默認(rèn)情況下，搜索請求會返回文檔_source的內(nèi)容，但與Rest API中的內(nèi)容一樣，你可以覆蓋此行為，例如，你可以完全關(guān)閉_source檢索：

sourceBuilder.fetchSource(false);

該方法還接受一個或多個通配符模式的數(shù)組，以控制以更精細(xì)的方式包含或排除哪些字段：

String[] includeFields = new String[] {"title", "user", "innerObject.*"};
String[] excludeFields = new String[] {"_type"};
sourceBuilder.fetchSource(includeFields, excludeFields);

通過在SearchSourceBuilder上設(shè)置HighlightBuilder，可以實現(xiàn)高亮搜索結(jié)果，通過將一個或多個HighlightBuilder.Field實例添加到HighlightBuilder，可以為每個字段定義不同的高亮行為。

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
HighlightBuilder highlightBuilder = new HighlightBuilder(); 
HighlightBuilder.Field highlightTitle =
        new HighlightBuilder.Field("title"); 
highlightTitle.highlighterType("unified");  
highlightBuilder.field(highlightTitle);  
HighlightBuilder.Field highlightUser = new HighlightBuilder.Field("user");
highlightBuilder.field(highlightUser);
searchSourceBuilder.highlighter(highlightBuilder);

創(chuàng)建一個新的HighlightBuilder。

為title字段創(chuàng)建字段高光色。

設(shè)置字段高光色類型。

將字段高光色添加到高亮構(gòu)建器。

Rest API文檔中有許多選項需要詳細(xì)說明，Rest API參數(shù)（例如pre_tags）通常由具有相似名稱的setter更改而來（例如#preTags(String ...)）。

稍后可以從SearchResponse中檢索高亮的文本片段。

可以通過先創(chuàng)建適當(dāng)?shù)?b>AggregationBuilder然后在SearchSourceBuilder上設(shè)置聚合來將聚合添加到搜索中，在以下示例中，我們在公司名稱上創(chuàng)建terms聚合 ，使用子聚合在公司員工平均年齡上：

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
TermsAggregationBuilder aggregation = AggregationBuilders.terms("by_company")
        .field("company.keyword");
aggregation.subAggregation(AggregationBuilders.avg("average_age")
        .field("age"));
searchSourceBuilder.aggregation(aggregation);

構(gòu)建聚合頁面提供了所有可用的聚合的列表及其對應(yīng)的AggregationBuilder對象和AggregationBuilders輔助方法。

稍后我們將看到如何訪問SearchResponse中的聚合。

要向搜索請求添加建議，請使用從SuggestBuilders工廠類中可輕松訪問的SuggestionBuilder的實現(xiàn)之一，Suggestion構(gòu)建器需要添加到頂級SuggestBuilder，它本身可以在SearchSourceBuilder上設(shè)置。

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
SuggestionBuilder termSuggestionBuilder =
    SuggestBuilders.termSuggestion("user").text("kmichy"); 
SuggestBuilder suggestBuilder = new SuggestBuilder();
suggestBuilder.addSuggestion("suggest_user", termSuggestionBuilder); 
searchSourceBuilder.suggest(suggestBuilder);

為user字段和文本kmichy創(chuàng)建一個新的TermSuggestionBuilder。

添加suggestion構(gòu)建器并將其命名為suggest_user。

我們稍后將看到如何從SearchResponse中檢索suggestion。

分析API可用于分析特定搜索請求的查詢和聚合的執(zhí)行情況，為了使用它，必須在SearchSourceBuilder上將profile標(biāo)志設(shè)置為true：

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
searchSourceBuilder.profile(true);

執(zhí)行SearchRequest后，相應(yīng)的SearchResponse將包含分析結(jié)果。

以下列方式執(zhí)行SearchRequest時，客戶端在繼續(xù)執(zhí)行代碼之前等待返回SearchResponse：

SearchResponse searchResponse = client.search(searchRequest, RequestOptions.DEFAULT);

執(zhí)行SearchRequest也可以以異步方式完成，以便客戶端可以直接返回，用戶需要通過將請求和監(jiān)聽器傳遞給異步搜索方法來指定響應(yīng)或潛在的故障如何處理：

client.searchAsync(searchRequest, RequestOptions.DEFAULT, listener);

要執(zhí)行的SearchRequest和執(zhí)行完成時要使用的ActionListener。

異步方法不會阻塞并且立即返回，完成后，如果執(zhí)行成功完成則使用onResponse方法回調(diào)ActionListener，如果失敗則使用onFailure方法。

SearchResponse的典型監(jiān)聽器如下所示：

ActionListener listener = new ActionListener() {
    @Override
    public void onResponse(SearchResponse searchResponse) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};

onResponse：執(zhí)行成功完成時調(diào)用。

onFailure：在整個SearchRequest失敗時調(diào)用。

通過執(zhí)行搜索返回的SearchResponse提供有關(guān)搜索執(zhí)行本身以及對返回文檔的訪問的詳細(xì)信息，首先，有關(guān)于請求執(zhí)行本身的有用信息，例如HTTP狀態(tài)碼，執(zhí)行時間或請求是提前終止還是超時：

RestStatus status = searchResponse.status();
TimeValue took = searchResponse.getTook();
Boolean terminatedEarly = searchResponse.isTerminatedEarly();
boolean timedOut = searchResponse.isTimedOut();

其次，響應(yīng)還通過提供有關(guān)搜索影響的碎片總數(shù)以及成功與不成功碎片的統(tǒng)計信息的碎片級別執(zhí)行的信息，可以通過在ShardSearchFailures上迭代數(shù)組來處理可能的失敗，如下例所示：

int totalShards = searchResponse.getTotalShards();
int successfulShards = searchResponse.getSuccessfulShards();
int failedShards = searchResponse.getFailedShards();
for (ShardSearchFailure failure : searchResponse.getShardFailures()) {
    // failures should be handled here
}

要訪問返回的文檔，我們需要先獲取響應(yīng)中包含的SearchHits：

SearchHits hits = searchResponse.getHits();

SearchHits提供有關(guān)所有匹配的全局信息，例如總命中數(shù)或最高分?jǐn)?shù)：

long totalHits = hits.getTotalHits();
float maxScore = hits.getMaxScore();

嵌套在SearchHits中的是可以迭代的單個搜索結(jié)果：

SearchHit[] searchHits = hits.getHits();
for (SearchHit hit : searchHits) {
    // do something with the SearchHit
}

SearchHit提供對每個搜索命中的索引、類型、docId和分?jǐn)?shù)等基本信息的訪問：

String index = hit.getIndex();
String type = hit.getType();
String id = hit.getId();
float score = hit.getScore();

此外，它還允許你以簡單的JSON-String或鍵/值對映射的形式返回文檔源，在此映射中，常規(guī)字段由字段名稱鍵控并包含字段值，多值字段作為對象列表返回，嵌套對象作為另一個鍵/值映射返回，這些案例需要相應(yīng)地進(jìn)行投射：

String sourceAsString = hit.getSourceAsString();
Map sourceAsMap = hit.getSourceAsMap();
String documentTitle = (String) sourceAsMap.get("title");
List