Elasticsearch Java Rest Client API 整理总结 (二) —— SearchAPI

发布日期:2019-10-14

目录

引言High REST ClientSearch APIsSearch API结语

引言

在上一篇 中主要整理了 Document API,本节中主要讲解 search API

High REST Client

Search APIs

Java High Level REST Client 支持下面的 Search API:

Search APISearch Scroll APIClear Scroll APIMulti-Search APIRanking Evaluation API

对于普通查询需求来说, Search API 使用最多,本篇只介绍这一部分。

Search API

Search Request

searchRequest 用来完成和查询文档,聚合文章,获取查询建议以及提供了各种方式来完成对查询结果的高亮操作。

最基本的查询操作如下

SearchRequest searchRequest = new SearchRequest(); SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); searchSourceBuilder.query(QueryBuilders.matchAllQuery()); // 添加 match_all 查询searchRequest.source(searchSourceBuilder); // 将 SearchSourceBuilder 添加到 SeachRequest 中

可选参数

限制 index, 限制 type

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

使用 SearchSourceBuilder

对查询行为的配置可以使用 SearchSourceBuilder 来完成,先来看一个实例

SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); // 默认配置sourceBuilder.query(QueryBuilders.termQuery("user", "kimchy")); // 设置查询,可以是任何类型的 QueryBuildersourceBuilder.from(0); // 起始 indexsourceBuilder.size(5); // 大小 sizesourceBuilder.timeout(new TimeValue(60, TimeUnit.SECONDS)); // 设置查询的超时时间

设置完成,添加到 SearchRequest 中。

SearchRequest searchRequest = new SearchRequest();searchRequest.source(sourceBuilder);

构建查询条件

查询请求是通过使用 QueryBuilder 对象来完成的,并且支持 Query DSL

使用构造函数创建 QueryBuilder

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

QueryBuilder 创建后,就可以通过各种方法来配置查询选项:

matchQueryBuilder.fuzziness(Fuzziness.AUTO); // 模糊查询matchQueryBuilder.prefixLength(3); // 前缀查询的长度matchQueryBuilder.maxExpansions(10); // max expansion 选项,用来控制模糊查询

也可以使用QueryBuilders 工具类来创建 QueryBuilder 对象。这个类提供了函数式编程风格的各种方法用来快速创建 QueryBuilder 对象。

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

不论什么方式创建的 QueryBuilder ,最后都需要添加到 `SearchSourceBuilder

searchSourceBuilder.query(matchQueryBuilder);

构建查询 文档中提供了一个丰富的查询列表,大家可以去参考。

指定排序

SearchSourceBuilder 允许添加一个或多个SortBuilder 实例。这里包含 4 种特殊的实现, (Field-, Score-, GeoDistance-ScriptSortBuilder)

sourceBuilder.sort(new ScoreSortBuilder().order(SortOrder.DESC)); // 根据分数 _score 降序排列 (默认行为)sourceBuilder.sort(new FieldSortBuilder("_uid").order(SortOrder.ASC)); // 根据 id 降序排列

过滤数据源

默认情况下,查询请求会返回文档的内容 _source ,当然我们也可以覆盖它。例如,禁止对 _source 的获取

sourceBuilder.fetchSource(false);

也可以使用通配符模式以更细的粒度包含或排除特定的字段:

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

高亮请求

可以通过在 SearchSourceBuilder 上设置 ·HighlightBuilder 完成对结果的高亮,而且可以配置字段具有不同的高亮行为。

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();HighlightBuilder highlightBuilder = new HighlightBuilder(); HighlightBuilder.Field highlightTitle = new HighlightBuilder.Field("title"); // title 字段高亮highlightTitle.highlighterType("unified"); // 配置高亮类型highlightBuilder.field(highlightTitle); // 添加到 builderHighlightBuilder.Field highlightUser = new HighlightBuilder.Field("user");highlightBuilder.field(highlightUser);searchSourceBuilder.highlighter(highlightBuilder);

聚合请求

链接

建议请求

链接

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

分析请求和聚合

分析 API 可用来对一个特定的查询操作中的请求和聚合进行分析,此时要将SearchSourceBuilder 的 profile标志位设置为 true

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

只要 SearchRequest 执行完成,对应的 SearchResponse 响应中就会包含 分析结果

同步执行

SearchResponse searchResponse = client.search(searchRequest);

异步执行

异步执行使用的是 listener 对结果进行处理。

ActionListener<SearchResponse> listener = new ActionListener<SearchResponse>() { @Override public void onResponse(SearchResponse searchResponse) { // 查询成功 } @Override public void onFailure(Exception e) { // 查询失败 }};

查询响应 SearchResponse

查询执行完成后,会返回 SearchResponse 对象,并在对象中包含查询执行的细节和符合条件的文档集合。

归纳一下, SerchResponse 包含的信息如下

请求本身的信息,如 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}

检索 SearchHits

要访问返回的文档,首先要在响应中获取其中的 SearchHits

SearchHits hits = searchResponse.getHits();

SearchHits 中包含了所有命中的全局信息,如查询命中的数量或者最大分值:

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

查询的结果嵌套在 SearchHits 中,可以通过遍历循环获取

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

SearchHit 提供了如 indextypedocId 和每个命中查询的分数

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

而且,还可以获取到文档的源数据,以 JSON-String 形式或者 key-value map 对的形式。在 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");

结语

本篇包含了 Java High level Rest Client 的 SearchAPI 部分,下篇会包含 查询构建 Building Queries,敬请期待~