Elasticsearch Java Rest Client API 整理总结 (二) —— SearchAPI
目录
引言
在 中主要整理了 document api,本节中主要讲解 search api
high rest client
search apis
java high level rest client 支持下面的 search 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")); // 设置查询,可以是任何类型的 querybuilder sourcebuilder.from(0); // 起始 index sourcebuilder.size(5); // 大小 size sourcebuilder.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); // 添加到 builder highlightbuilder.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
提供了如 index
, type
, docid
和每个命中查询的分数
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,敬请期待~
推荐阅读
-
Elasticsearch Java Rest Client API 整理总结 (一)
-
Elasticsearch Java Rest Client API 整理总结 (二) —— SearchAPI
-
Elasticsearch Java Rest Client API 整理总结 (三)——Building Queries
-
Elasticsearch Java Rest Client API 整理总结 (二) —— SearchAPI
-
Elasticsearch Java Rest Client API 整理总结 (一)
-
Elasticsearch Java Rest Client API 整理总结 (三)——Building Queries