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

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

    推荐阅读