elasticsearch——Rest Client

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); //执行删除操作

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文档为准）