Elasticsearch官方提供了Java API供开发者使用。目前ElasticSearch的Java API内容非常多，而且更新非常的频繁。所以你现在在网上查找到的各种博客，里面的API是7.x的版本，目前最新的API已经到了8.x。而我们平时Java程序里使用Elasticsearch最多的场景便是搜索数据。因此核心还是要把Elasticsearch提供的关于搜索的文档理解透才可以在各种版本迭代中更快上手

理解Search API

Search API 官方文档

我们都知道，Elasticsearch的各种API都是很标准的Restful风格，一个标准的请求如下

GET /<target>/_search
{
  json format request body
}
1
2
3
4

target是我们要查询的index的名字，关键是request body。我们平时的一般开发场景request body里的属性基本是下面这些。

也就是我的过滤条件是什么？返回结果如何排序？如何只返回部分字段？如何分页？这几种常见需求

{
	"query": {},
	"sort": [],
	"search_after": [],
	"_source": {},
	"from": 0,
	"size": 2
}
1
2
3
4
5
6
7
8

大方向其实也就6种，下面简单逐一解释

1. query部分是查询的核心，里面需要书写我们各种各样的查询条件

2. sort不难理解是排序

   "sort": [{
     "field1": {
       "order": "desc"
     }
   },{
     "field2": {
       "order": "asc"
     }
   }]
   1
   2
   3
   4
   5
   6
   7
   8
   9

3. search_after是在进行深度分页时，Elasticsearch官方建议使用的写法。Elasticsearch默认最大返回条数是10000.其内容是分页之后的最后一条记录的sort内容，下一次查询时，把sort内容放到search_after里即可实现分页查询

   "search_after": [{
     "field1": {
       "order": "desc"
     }
   },{
     "field2": {
       "order": "asc"
     }
   }]
   1
   2
   3
   4
   5
   6
   7
   8
   9

   这里放的就是上面示例中sort的内容

4. _source是告知查询结果返回哪些字段，有的时候我们并不需要文档的全部内容，可能只需要几个。这个时候就用上__source参数

     "_source": {
       "includes": ["field1","field2"],
       "excludes": ["field3"]
    }
   1
   2
   3
   4

5. from和size都理解，就不解释了。注意当使用search_after时，from必须从0开始，from默认也是0

我们平时普通开发也就这些需求了，所以这几个字段可以满足绝大部分的情况

理解DSL

我们知道了一个完整的请求都有哪些结构，并分析了结构中每一部分的作用。这一部分，我们着重理解关键的查询语句的部分

DSL官方文档

这段话说得非常清楚，首先DSL是基于JSON格式；其次，DSL分为两个部分，叶子查询和复合查询，其中叶子查询是针对特定field的查询，而复合查询是由其他叶子查询或其他复合查询组成的

看完这两段话，我们基本有了一个清晰的认识

• 对field的值的查询，那么必定是叶子查询
• 多个叶子查询组成的复合查询最终构成了我们的查询条件

基于这个认识，我们再深一步了解具体语法。在了解过程中，你会发现，只要你看懂了上面文档的那段话，各种查询条件的写法就像写SQL一样丝滑

如何看文档？

平时查阅文档时，重点关注下面标红的部分

复合查询

可以看到，在bool复合查询里，有4种复合查询供我们使用，写法为

{
  "query": {
    "bool": {
      "must": [],
      "must_not": [],
      "should": [],
      "filter": []
    }
  }
}
1
2
3
4
5
6
7
8
9
10

第一部分我们完成了。下面我们要为复合查询里面开始配置叶子查询

叶子查询

这里以match为例，其他查询写法大同小异

{
  	"query": {
    "bool": {
      "must": [
        {
          "match": {
            "article_content": {
              "query": "FNoHmw1hI4"
            }
          }
        },
        {
          "match": {
            "author": {
              "query": "9vCOv"
            }
          }
        }
      ]
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

可以看到，这里我们是在must这个复合查询里设置了2个match叶子查询。

注意：每一个叶子查询的写法都不一样，不一定都是query。具体文档直接去找上面的文档即可。关键是要领会思想，灵活变通。只要思路对了，至于写法，这是查阅文档熟练度的问题

完整的写法

学习DSL初期可以利用Kibana的Dev Tools来练习，主要是里面有补全。多写就熟能生巧了。而且一旦你的写法不对，它的补全是不会有提示的，除了个别情况之外，例如_source

一个完整的实例

POST article-2022/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "article_content": {
              "query": "FNoHmw1hI4"
            }
          }
        },
        {
          "match": {
            "author": {
              "query": "9vCOv"
            }
          }
        }
      ]
    }
  },
  "sort": [
  {
    "create_time": {
      "order": "desc"
    }
  }
],
  "_source": {
  "includes": ["author","article_content"],
  "excludes": ["create_time"]
},
  "from": 0, 
  "size": 2
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

根据DSL使用Java API

完全理解了上面的DSL，那么用Java API那是水到渠成。这里给个简单的例子

public List<String> simpleSearchArticle(String queryContent) {
        List<String> result = new ArrayList<>();
        Query query = QueryBuilders.bool().must(m -> m.match(mt -> mt.field("article_content").query(queryContent))).build()._toQuery();
        SearchRequest searchRequest = new SearchRequest.Builder()
            .index(INDEX_PREFIX+"*")
            .query(query)
            .source(s-> s.filter(f-> f.includes("article_content")))
            .build();
        SearchResponse<Article> search = elasticsearchClient.search(searchRequest, Article.class);
        List<Hit<Article>> hits = search.hits().hits();
        hits.forEach(item -> {
            result.add(item.id());
            log.info(item.source().getArticleContent());
        });
        return result;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

应该很好看懂，组织结构就是.index.query.source，query的部分又是bool.must(match)，这里没有加分页。不过理解了上面的DSL和Search API部分，分分钟就搞定了。

所以你看，经过了前面两章的学习，真正使用API的时候，只要知道入口是什么(具体的Builder是什么)，后面的部分就顺理成章写出来了，都不用去网上查资料和各种百度。无论API怎么变，你只要理解了他最终的形式是什么，那你就很轻松的知道你的入口点在哪里

打印请求日志

Elasticsearch的Java API还提供了打印请求日志，如果你不确定自己的API使用的对不对，可以开启下面的日志。最终在Java内部请求ES的时候，会打印出curl格式的请求日志，这点对开发初期不熟悉API的同学和后期调试又或者是生产环境定位问题很有帮助

logging:
  level:
    org.elasticsearch: debug
    tracer: trace
1
2
3
4

其他资源

• 示例源码仓库
• Elasticsearch各种查询示例
• Java API以https的方式连接ELK