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

目录

• high rest client
  • search apis

引言

在 中主要整理了 document api，本节中主要讲解 search api

high rest client

search apis

java high level rest client 支持下面的 search api：

• search api
• search scroll api
• clear scroll api
• multi-search api
• ranking 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")); // 设置查询，可以是任何类型的 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，敬请期待~