elasticsearch——Rest|elasticsearch——Rest Client elasticsearch——RestClient

elasticsearch版本迭代太快，项目中用的5.X版本，java client使用了新推出的Rest Client。而网上的client大多是还是TransportClient。组里封装的EsClient不满足业务需求，只能自己研究下Rest Client。Rest Client为推荐使用，TransportClient将在未来版本中废弃。新版本的很多api都发生了变化，改名了或者换地方了。。。

这里提供一个elasticsearch5.6 java rest client的中文文档：https://legacy.gitbook.com/book/quanke/elasticsearch-java-rest/details。本文章只是简单应用，详细细节参考此文档。

介绍 java rest client有两个实现类，分别是RestClient和RestHighLevelClient。前者是一个低级客户端，通过Http与elasticsearch集群进行通信，可以做到负载均衡、故障转移、持久化链接、自动发现集群节点等功能，同时支持所有elasticsearch版本，但是需要自己对请求和相应做编解码（自己写JSON）；后者是一个高级客户端，对增删改差进行了封装，不需要处理编解码，类似之前的TransportClient，但是兼容性较差，对客户端和集群版本要求较高。
因为RestClient没有提供增删改差方法，只能自己写json并选择Http请求的方法进行实现，一般使用较少，只有RestHighLevelClient无法满足的情况下才会使用。这里主要介绍RestHighLevelClient。
RestHighLevelClient

RestHighLevelClient restHighLevelClient = new RestHighLevelClient(restClient);

RestHighLevelClient仅仅是对RestClinet的一个封装。支持异步请求。
search api 请求构造查询主要用到两个类：SearchRequest和SearchSourceBuilder。

SearchRequest searchRequest = new SearchRequest(); //穿件SeachRequest，Without arguments this runs against all indices. SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); // 大多数的搜索参数被添加到 SearchSourceBuilder 。它为每个进入请求体的每个东西都提供 setter 方法。 searchSourceBuilder.query(QueryBuilders.matchAllQuery()); // 添加一个 match_all 查询到 searchSourceBuilder 。 searchRequest.source(searchSourceBuilder); //将searchSourceBuilder添加到searchRequest

这里构造了一个查询请求，内容为一个match_all查询。
SearchRequest为最终的查询请求封装，而查询的大部分细节由SearchSourceBuilder指定。
首先来看一下常用的几个SearchRequest方法

SearchRequest searchRequest = new SearchRequest("posts"); // 限制请求到某个索引上 searchRequest.indices("gets"); //设定索引 searchRequest.types("doc"); // 限制请求的类别

Es-java包中请求体封装类，其属性的setter和getter方法，都没有相应的set和get标记，直接使用属性名作为方法名，然后通过入参和返回值区分哪个是setter哪个是getter。之前版本中用的标准setter和getter在（至少在5.X）客户端中已经不见了。

还有很多其他的配置参数，这里不再罗列。
然后是搜索细节——SearchSourceBuilder
SearchSourceBuilder可以配置大多数的搜索细节，以下为几个实例，详细参考文档：

SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); //使用默认选项创建 SearchSourceBuilder 。 sourceBuilder.query(QueryBuilders.termQuery("user", "kimchy")); //设置查询对象。可以使任何类型的 QueryBuilder sourceBuilder.from(0); //设置from选项，确定要开始搜索的结果索引。默认为0。 sourceBuilder.size(5); //设置大小选项，确定要返回的搜索匹配数。默认为10。 sourceBuilder.timeout(new TimeValue(60, TimeUnit.SECONDS)); //设置一个可选的超时时间，用于控制搜索允许的时间。

sourceBuilder.query：设置查询对象。所有Query DSL支持的搜索类型都有对应的QueryBuilder。创建QueryBuilder有两种方式：直接new和QueryBuilders工厂方法，我习惯后者（实际没差别）。常见的QueryBuilder列几个：

// 创建一个字段“user”与文本“kimchy”相匹配的的全文匹配查询。 MatchQueryBuilder matchQueryBuilder = new MatchQueryBuilder("user", "kimchy"); // 创建一个字段date的范围查询。 RangeQueryBuilder rangeQueryBuilder = QueryBuilders.rangeQuery("date").lte(time);

每个QueryBuilder都根据各自的查询提供了对应的方法，同时支持链式创建并初始化。
QueryBuilder支持像curl一样进行查询嵌套，比如一个bool的must里套一个bool，should里放一个bool一个range。
无论怎么嵌套，最终得到的QueryBuilder结构就像传统的search json一样。最后把这个QueryBuilder添加到SearchSourceBuilder中：

searchSourceBuilder.query(queryBuilder);

每个SearchSourceBuilder只能设定一个QueryBuilder，即一个Query DSL中只有一个query元素。
在传统Query DSL中，还有一些在结构上与query并列的，比如sort，在java中表示如下：

FieldSortBuilder sortBuilder = SortBuilders.fieldSort(sortField).order(sortOrder); searchSourceBuilder.sort(sortBuilder);

可以控制一次返回文档的个数、返回文档的字段：

searchSourceBuilder.size(num); searchSourceBuilder.fetchSource(includeFields, excludeFields);

实现高亮：

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); HighlightBuilder highlightBuilder = new HighlightBuilder(); //创建一个HighlightBuilder HighlightBuilder.Field highlightTitle =new HighlightBuilder.Field("title"); //指定高亮字段1 highlightBuilder.field(highlightTitle); //指定高亮字段2 highlightBuilder.preTags(preTags); //修改高亮前缀（默认http标签） highlightBuilder.postTags(postTags); //修改高亮后缀（默认http标签） searchSourceBuilder.highlighter(highlightBuilder);

然后可以从结果中获取高亮显示的文本字段。
实现聚合：

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

详细方法参考聚合api。
响应

SearchResponse searchResponse = client.search(searchRequest);

通过SearchResponse获得所有的相应数据。

无论请求还是相应，想要构造或者解析都需要按照DSL的格式，一层一层去做。

可以遍历返回的文档：

SearchHits hits = searchResponse.getHits(); //获得hits数组 long totalHits = hits.getTotalHits(); //获取检索的文档总数（不是这次返回的数量） for (SearchHit hit : hits) { String index = hit.getIndex(); //获取文档的index String type = hit.getType(); //获取文档的type String id = hit.getId(); //获取文档的id Map sourceMap = hit.getSource(); //获取文档内容，封装为map String sourceString = hit.getSourceAsString(); //获取文档内容，转换为json字符串。 }

这里遍历，官方使用了

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

其实SearchHits实现了Iterable接口，可以直接进行迭代。
hit中除了source之外的字段，也可以进行获取，以高亮为例：

Map highlightFields = hit.getHighlightFields(); HighlightField highlight = highlightFields.get("title"); //获取该title领域的突出显示 Text[] fragments = highlight.fragments(); //获取包含突出显示的字段内容的一个或多个片段 String fragmentString = fragments[0].string();

聚合的话不在Hits中，需要从SearchResponse中获取Aggregations对象：

Aggregations aggregations = searchResponse.getAggregations(); Terms byCompanyAggregation = aggregations.get("by_company"); //Get the by_company terms aggregation Bucket elasticBucket = byCompanyAggregation.getBucketByKey("Elastic"); // Avg averageAge = elasticBucket.getAggregations().get("average_age"); //Get the average_age sub-aggregation from that bucket double avg = averageAge.getValue();

其他参考官方API。
游标 5.X版本中的游标使用也跟之前有了不同，下面简单介绍：

final Scroll scroll = new Scroll(TimeValue.timeValueMinutes(1L)); // 创建游标对象 SearchRequest searchRequest = new SearchRequest("posts"); searchRequest.scroll(scroll); // 为查询设置游标，注意是在SearchRequest中配置 SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); searchSourceBuilder.query(matchQuery("title", "Elasticsearch")); searchRequest.source(searchSourceBuilder); SearchResponse searchResponse = client.search(searchRequest); //通过发送初始化 SearchRequest 来初始化搜索上下文 String scrollId = searchResponse.getScrollId(); // 获取scrollId SearchHit[] searchHits = searchResponse.getHits().getHits(); while (searchHits != null && searchHits.length > 0) { //在一个循环中通过调用 Search Scroll api 检索所有搜索命中结果，知道没有文档返回为止。 //创建一个新的SearchScrollRequest，持有最近一次返回的滚动标识符和滚动间隔 SearchScrollRequest scrollRequest = new SearchScrollRequest(scrollId); scrollRequest.scroll(scroll); //重新设置游标ID searchResponse = client.searchScroll(scrollRequest); //游标查询，这里使用searchScroll，与第一次查询不同 scrollId = searchResponse.getScrollId(); //获取新的游标ID searchHits = searchResponse.getHits().getHits(); //处理返回的搜索结果 } ClearScrollRequest clearScrollRequest = new ClearScrollRequest(); //一旦查询全部完成，清除游标 clearScrollRequest.addScrollId(scrollId); ClearScrollResponse clearScrollResponse = client.clearScroll(clearScrollRequest); boolean succeeded = clearScrollResponse.isSucceeded();

delete api 在RestHighLevelClient中，删除只支持按照index/type/id进行精确删除，不支持delete by query的操作。普通的TransportClient支持delete by query。

DeleteRequest request = new DeleteRequest(indexName, type, id); //创建DeleteRequest对象 DeleteResponse response = client.delete(request); //执行删除操作

【elasticsearch——Rest|elasticsearch——Rest Client】DeleteRequest除了以上三个值，还有很多可选参数：

request.routing("routing"); // 路由值 request.parent("parent"); //Parent 值 request.timeout(TimeValue.timeValueMinutes(2)); // TimeValue 类型的等待主分片可用的超时时间 request.timeout("2m"); // 字符串类型的等待主分片可用的超时时间 request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // Refresh policy as a WriteRequest.RefreshPolicy instance request.setRefreshPolicy("wait_for"); // Refresh policy as a String request.version(2); // Version request.versionType(VersionType.EXTERNAL); // Version type

相应DeleteResponse可以获得操作结果的各种信息：

String index = deleteResponse.getIndex(); // index String type = deleteResponse.getType(); // type String id = deleteResponse.getId(); // id long version = deleteResponse.getVersion(); .// version

index api

IndexRequest request = new IndexRequest( "posts", //Index "doc", //Type "1"); //Document id String jsonString = "{" + "\"user\":\"kimchy\"," + "\"postDate\":\"2013-01-30\"," + "\"message\":\"trying out Elasticsearch\"" + "}"; request.source(jsonString, XContentType.JSON); /以字符串提供的 Document source

这里使用IndexRequest做index请求。包括index\type\id信息，然后创建了index文档，这里采用字符串方式。
文档可以使用多种方式提供，包括字符串、Map、XContentBuilder、Object数组、BytesReference、键值对数组等方式：

Map jsonMap = new HashMap<>(); jsonMap.put("user", "kimchy"); jsonMap.put("postDate", new Date()); jsonMap.put("message", "trying out Elasticsearch"); IndexRequest indexRequest = new IndexRequest("posts", "doc", "1").source(jsonMap); //Map 作为文档源，它可以自动转换为 JSON 格式。XContentBuilder builder = XContentFactory.jsonBuilder(); builder.startObject(); { builder.field("user", "kimchy"); builder.field("postDate", new Date()); builder.field("message", "trying out Elasticsearch"); } builder.endObject(); IndexRequest indexRequest = new IndexRequest("posts", "doc", "1").source(builder); //XContentBuilder 对象作为文档源，由 Elasticsearch 内置的帮助器生成 JSON 内容IndexRequest indexRequest = new IndexRequest("posts", "doc", "1") .source("user", "kimchy", "postDate", new Date(), "message", "trying out Elasticsearch"); //以键值对对象作为文档来源，它自动转换为 JSON 格式

other api 待续。。。（各种api以官方rest client文档为准）