ElasticSearch Java High level Rest Client 官方文档中文翻译 二 (search API)

ElasticSearch Java High level Rest Client 官方文档中文翻译 二 （search API）

SearchAPI

Search Request

SearchRequest可用于搜索文档，聚合文档，还有搜索结果的高亮显示

SearchRequest的最基础的形式

1. 构建searchRequest如果没有参数，这将与所有索引冲突。
2. 可用使用SearchSourceBuilder添加搜索的参数，SearchSourceBuilder通过setter设置请求体中的搜索参数
3. 在SearchSourceBuilder添加match_all 查询
4. 将SearchSourceBuilder添加到SearchRequest中

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

可选参数

• Restricts the request to an index ： 将请求限制为索引

SearchRequest searchRequest = new SearchRequest("posts"); 

• Set a routing parameter 设置路由参数

searchRequest.routing("routing"); 

•   Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded
  

设置IndicesOptions控制如何解决不可用的索引以及如何扩展通配符表达式

searchRequest.indicesOptions(IndicesOptions.lenientExpandOpen()); 

• Use the preference parameter e.g. to execute the search to prefer local shards. The default is to randomize across shards.

使用首选项参数，例如，执行搜索以偏爱本地碎片。默认设置是随机分片。

searchRequest.preference("_local"); 

构建SearchSourceBuilder

许多控制搜索的行为都可以通过SearchSourceBuilder来设定，该选项或多或少包含与Rest API的搜索请求正文中的选项等效的选项。

• 创建SearchSourceBuilder对象
• 设置查询方式，可以是QueryBuilder的任何方式
• 设置分页数 的其实位置
• 设置每页显示的数据
• 设置搜索的超时时间

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

搜索条件构造好了之后，将SearchSourceBuilder假如到SearchRequest中即可

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

Building queries 绑定查询

需要通过QueryBuilder兑现过来创建搜索条件，QueryBuilder支持所有的Elasticsearch QueryDSL.
可以通过QueryBuilder构造器创建QueryBuilder

• 创建一个全文匹配的搜索条件，需要匹配user 域的 kimchy

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

一旦创建完成之后之后，QueryBuilder对象将提供方法来配置其创建的搜索查询的选项：

• 对匹配查询启用模糊匹配
• 在匹配查询中设置前缀长度选项
• 设置最大扩展选项以控制查询的模糊过程

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

也可以通过流式编程创建QueryBuilder

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

不管你用什么方式创建QueryBuilder，都必须将其加入到searchSourceBuilder中。

在 Building Queries页面给出了可用的所有QueryBuilder方法。

Specifying Sorting 指定排序

SearchSourceBuilder允许添加一个或者多个SortBuilder排序实例，有四种具体的排序实现
Field score GeoDistance ScriptSortBuilder

• 搜索结果按照_score降序排序
• 搜索结果按照_id升序排序

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

Source filtering 过滤源数据

默认的情况下，搜索请求返回文档中的_source，你也可以关掉这一选项。

sourceBuilder.fetchSource(false);

这个方法也可以过滤掉我们不想要的fields

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

Request Highlighting 请求高亮

高亮搜索的结果可以通过在SearchSourceBuilder设置HighlightBuilder来实现。不同的高亮表现可以通过设置不同的HighlightBuilder.Field来实现

• Creates a new HighlightBuilder 创建HighlightBuilder对象
• Create a field highlighter for the title field 为title字段设置高亮属性
• Set the field highlighter type 设置高亮的种类
• highlightTitle 添加到 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);

Requesting Aggregations 聚合搜索结果

可以通过在初始的创建合适的AggregationBuilder并将其加入到SearchSourceBuilder来实现聚合查询。
在下面的例子中我们创建了以company name 为组的聚合器，同时还聚合了员工平均工资的操作。

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

更多聚合操作 在 Building Aggregations 页

Requesting Suggestions

要将“建议”添加到搜索请求中，请使用SuggestionBuilder可从SuggestBuilders工厂类轻松访问的实现之一。建议建设者需要添加到顶层SuggestBuilder，它本身可以在上设置 SearchSourceBuilder。

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

Profiling Queries and Aggregations 分析查询汇总

Profile API 可以分析查询请求的执行过程也可以聚合特定的查询结果，如果想要使用它，就必须将SearchSourceBuilde上的分析标记打开

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

一旦查询请求被执行了，那么在查询响应中就会有查询请求分析的结果

Synchronous execution 同步执行

ASynchronous execution

SearchResponse

在SearchResponse 不仅返回了需要搜索的文档，同样也服务器也返回了本次搜索的执行详情，类似于HTTP响应头，状态码。

本次查询请求的信息 状态，耗时，是否超时

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

第二，响应中同样也提供了关于分片的信息，比如本次查询请求影响了多少个分片，成功分片，失败分片。

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

Retrieving SearchHits

为了得到返回的文档，我们需要首先得到response中的SearchHits对象。

SearchHits hits = searchResponse.getHits();

SearchHits 提供了命中文档的一些全局信息，比如命中的文档数，最大得分

TotalHits totalHits = hits.getTotalHits();
// the total number of hits, must be interpreted in the context of totalHits.relation
long numHits = totalHits.value;
// whether the number of hits is accurate (EQUAL_TO) or a lower bound of the total (GREATER_THAN_OR_EQUAL_TO)
TotalHits.Relation relation = totalHits.relation;
float maxScore = hits.getMaxScore();

嵌套在中的SearchHits是可以迭代的各个搜索结果：

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

SearchHit提供了搜索索引的基本信息，如索引，文档id，得分

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

此外，SearchHit可以让你以Json 字符串的形式或者map 的形式获取到文档source 内容，在map里面中，常规字段由字段名称键入并包含字段值。多值字段以对象列表的形式返回，嵌套对象以另一个键/值映射的形式返回。这些情况需要相应地强制转换：

String sourceAsString = hit.getSourceAsString();
Map<String, Object> sourceAsMap = hit.getSourceAsMap();
String documentTitle = (String) sourceAsMap.get("title");
List<Object> users = (List<Object>) sourceAsMap.get("user");
Map<String, Object> innerObject =
        (Map<String, Object>) sourceAsMap.get("innerObject");

Retrieving HighLighting 搜索结果高亮显示

如果需要，可以通过结果中的每个SearchHit来截取文本片段的高亮显示。

SearchHits hits = searchResponse.getHits();
for (SearchHit hit : hits.getHits()) {
    Map<String, HighlightField> highlightFields = hit.getHighlightFields();
    HighlightField highlight = highlightFields.get("title"); 
    Text[] fragments = highlight.fragments();  
    String fragmentString = fragments[0].string();
}

Retrieving Aggregations 聚合函数操作

• 得到by-company 的aggregation字段
• Get the buckets that is keyed with Elastic
• average_age sub-aggregation

Aggregations aggregations = searchResponse.getAggregations();
Terms byCompanyAggregation = aggregations.get("by_company"); 
Bucket elasticBucket = byCompanyAggregation.getBucketByKey("Elastic"); 
Avg averageAge = elasticBucket.getAggregations().get("average_age"); 
double avg = averageAge.getValue();

请注意，如果按名称访问聚合，则需要根据请求的聚合类型指定聚合接口，否则ClassCastException将抛出a：

Range range = aggregations.get("by_company"); 

也可以将所有聚合作为以聚合名称作为关键字的映射来访问。在这种情况下，必须明确地强制转换为正确的聚合接口：

Map<String, Aggregation> aggregationMap = aggregations.getAsMap();
Terms companyAggregation = (Terms) aggregationMap.get("by_company");

还有一些getter会将所有顶级聚合返回为列表：

List<Aggregation> aggregationList = aggregations.asList();

您可以遍历所有聚合，然后例如根据其类型决定如何进一步处理它们：

for (Aggregation agg : aggregations) {
    String type = agg.getType();
    if (type.equals(TermsAggregationBuilder.NAME)) {
        Bucket elasticBucket = ((Terms) agg).getBucketByKey("Elastic");
        long numberOfDocs = elasticBucket.getDocCount();
    }
}

Retrieving Aggregations 检索建议

要从中获取建议SearchResponse，请使用Suggest对象作为入口点，然后检索嵌套的建议对象：

Suggest suggest = searchResponse.getSuggest(); 
TermSuggestion termSuggestion = suggest.getSuggestion("suggest_user"); 
for (TermSuggestion.Entry entry : termSuggestion.getEntries()) { 
    for (TermSuggestion.Entry.Option option : entry) { 
        String suggestText = option.getText().string();
    }
}

Retrieving profiling Results 检索分析结果

通过searchResponse的getProfileResults可以得到分析结果，返回Map<String, ProfileShardResult>

Map<String, ProfileShardResult> profilingResults =
        searchResponse.getProfileResults(); 
for (Map.Entry<String, ProfileShardResult> profilingResult : profilingResults.entrySet()) { 
    String key = profilingResult.getKey(); 
    ProfileShardResult profileShardResult = profilingResult.getValue(); 
}

所述ProfileShardResult对象本身包含一个或多个查询简档的结果，一个用于抵靠底层Lucene索引执行的每个查询：

List<QueryProfileShardResult> queryProfileShardResults =
        profileShardResult.getQueryProfileResults(); 
for (QueryProfileShardResult queryProfileResult : queryProfileShardResults) { 

}

每个都QueryProfileShardResult可以访问详细的查询树执行，并以ProfileResult对象列表的形式返回 ：

for (ProfileResult profileResult : queryProfileResult.getQueryResults()) { 
    String queryName = profileResult.getQueryName(); 
    long queryTimeInMillis = profileResult.getTime(); 
    List<ProfileResult> profiledChildren = profileResult.getProfiledChildren(); 
}

Rest API文档包含有关性能分析查询的更多信息，并带有查询性能分析信息的描述。

该QueryProfileShardResult还可以访问了Lucene的收集器的分析信息：

CollectorResult collectorResult = queryProfileResult.getCollectorResult();  
String collectorName = collectorResult.getName();  
Long collectorTimeInMillis = collectorResult.getTime(); 
List<CollectorResult> profiledChildren = collectorResult.getProfiledChildren(); 

Rest API文档包含有关Lucene收集器性能分析信息的更多信息。请参阅分析查询。
通过与查询树执行非常类似的方式，这些QueryProfileShardResult对象可以访问详细的聚合树执行：

AggregationProfileShardResult aggsProfileResults =
        profileShardResult.getAggregationProfileResults(); 
for (ProfileResult profileResult : aggsProfileResults.getProfileResults()) { 
    String aggName = profileResult.getQueryName(); 
    long aggTimeInMillis = profileResult.getTime(); 
    List<ProfileResult> profiledChildren = profileResult.getProfiledChildren(); 
}