Easy-ES

快速入门

一，简介

Easy-Es（简称EE）是一款基于ElasticSearch(简称Es)官方提供的RestHighLevelClient打造的ORM开发框架，在 RestHighLevelClient 的基础上,只做增强不做改变，为简化开发、提高效率而生,您如果有用过Mybatis-Plus(简称MP),那么您基本可以零学习成本直接上手EE,EE是MP的Es平替版,在有些方面甚至比MP更简单,同时也融入了更多Es独有的功能,助力您快速实现各种场景的开发。

二，优势

• 全自动索引托管: 全球开源首创的索引托管模式,开发者无需关心索引的创建更新及数据迁移等繁琐步骤,索引全生命周期皆可托管给框架,由框架自动完成,过程零停机,用户无感知,彻底解放开发者
• 智能字段类型推断: 根据索引类型和当前查询类型上下文综合智能判断当前查询是否需要拼接.keyword后缀,减少小白误用的可能
• 屏蔽语言差异: 开发者只需要会MySQL语法即可使用Es,真正做到一通百通,无需学习枯燥易忘的Es语法,Es使用相对MySQL较低频,学了长期不用也会忘,没必要浪费这时间.开发就应该专注于业务,省下的时间去撸铁,去陪女朋友陪家人,不做资本家的韭菜
• 代码量极少: 与直接使用RestHighLevelClient相比,相同的查询平均可以节省3-5倍左右的代码量
• 零魔法值: 字段名称直接从实体中获取,无需输入字段名称字符串这种魔法值,提高代码可读性,杜绝因字段名称修改而代码漏改带来的Bug
• 零额外学习成本: 开发者只要会国内最受欢迎的Mybatis-Plus语法,即可无缝迁移至EE,EE采用和前者相同的语法,消除使用者额外学习成本,直接上手,爽
• 降低开发者门槛: Es通常需要中高级开发者才能驾驭,但通过接入EE,即便是只了解ES基础的初学者也可以轻松驾驭ES完成绝大多数需求的开发,可以提高人员利用率,降低企业成本

三，特性

• 无侵入：只做增强不做改变，引入它不会对现有工程产生影响，如丝般顺滑
• 损耗小：启动即会自动注入基本 CURD，性能基本无损耗，直接面向对象操作
• 强大的 CRUD 操作：内置通用 Mapper，仅仅通过少量配置即可实现大部分 CRUD 操作，更有强大的条件构造器，满足各类使用需求
• 支持 Lambda 形式调用：通过 Lambda 表达式，方便的编写各类查询条件，无需再担心字段写错段
• 支持主键自动生成：支持2 种主键策略，可自由配置，完美解决主键问题
• 支持 ActiveRecord 模式：支持 ActiveRecord 形式调用，实体类只需继承 Model 类即可进行强大的 CRUD 操作
• 支持自定义全局通用操作：支持全局通用方法注入（ Write once, use anywhere ）
• 内置分页插件：基于RestHighLevelClient 物理分页，开发者无需关心具体操作，且无需额外配置插件，写分页等同于普通 List 查询,且保持和PageHelper插件同样的分页返回字段,无需担心命名影响
• MySQL功能全覆盖:MySQL中支持的功能通过EE都可以轻松实现
• 支持ES高阶语法:支持高亮搜索,分词查询,权重查询,Geo地理位置查询,IP查询,聚合查询等高阶语法
• 良好的拓展性:底层仍使用RestHighLevelClient,可保持其拓展性,开发者在使用EE的同时,仍可使用RestHighLevelClient的功能

四，使用场景

1. 检索类服务

• 搜索文库
• 电商商品检索
• 海量系统日志检索

2. 问答类服务(本质上也是检索类)

• 在线智能客服
• 机器人

3. 地图类服务

• 打车app
• 外卖app
• 社区团购配送
• 陌生人社交

五，性能

EE在整个查询过程中做了什么事? 其核心事宜总结起来就2件:

1. 把用户输入的MySQL语法(Mybatis-Plus语法)转换成RestHighLevel语法,然后调用RestHighLevelClient执行本次查询

2. 把查询结果转换成用户想要的格式:如List并返回.

EE除了查询会比直接使用RestHighLevelClient平均慢10-15毫秒,增删改API并无差异,而且随着查询数据量的增大,实体字段缓存生效后,查询差异会进一步降低,几乎可以忽略不计. 牺牲10毫秒,对用户而言是无感知的,但对开发而言,可以节省大量代码和时间,我认为这是值得的,基本上没有哪款ORM框架是不会损耗性能的

六，安全

我们已接入OSCS墨菲安全扫描,ee源码中未被扫描出任何风险项(超越100%的项目),确保人畜无害! 大家可放心使用,当然如果您仍不放心,我们推荐您在使用前下载ee源码亲自阅读一番,我们是100%开源,是否有风险您一看便知. 另外本框架所有三方依赖有elastic search官方提供的es操作套件和RestHighLevelClient,阿里的fastJson,Spring官方的SpringbootAutoConfig,Apache的commons-codec以及Lombok,无二方依赖,空口黄牙,口说无凭,大家可以点开maven中央仓库,亲自查看一番:maven中央仓库 (opens new window)以上套件即使不使用EE,你在实际开发中也会用到,且都是官方出品,所以您无需担心. 那么EE有没有可能有安全问题?毕竟是个人开发者写的,没有前面提到的框架那么强的背书.首先我认为任何框架都有可能有安全风险,即便是有强大的公司背书,比如前阵子阿里FastJson的安全漏洞. 对于EE,我个人认为目前不会有特别严重的安全问题,EE框架的核心原理上面的图中已经列出来了,EE的核心原理只是转换,相当于一个翻译或者中介,并无其它涉及安全类的操作,加上EE框架本身十分轻量,没有引入任何多余的类库,所有工具类都是自己封装,封装的时候也参照了apache工具类,所以有理由认为使用EE是相对安全的,除非下游的官方依赖本身有安全漏洞. 另外关于FastJson其实一直争议不断,其性能确实是目前市面上当之无愧的一哥,确实够快,安全方面的话之前因为AutoType问题和黑客上演的魔高一尺道高一丈故事,让很多人误以为它漏洞百出,其实它没有那么不堪,之前的漏洞频繁本质上都是一个问题.阿里内部尚且那么多项目在使用FastJson,只要其社区活跃,并有积极处理,都是可以考虑使用的,毕竟没有哪个框架可以保证完全没有漏洞,只不过还没被发现罢了.当前依赖的fastjson为其最新版本,墨菲扫描无任何漏洞. 我们单元测试用例综合覆盖率超95%,已上线的所有功能均有测试用例覆盖,且经过生产环境和开源社区大量用户使用验证,敬请放心使用.

七，拓展性

EE底层用的就是Es官方提供的RestHighLevelClient,我们只是对RestHighLevelClient做了增强,并没有改变减少或是削弱它原有的功能,所以您无需担心拓展性. 任何框架的使用都会降低系统的灵活性,因为框架是死的,使用了以后不可避免的会碰到一些场景框架无法满足,需要定制化开发,或是短期内您不了解框架本身,不敢贸然使用,不然以后遇到问题怎么办? 为了解决上述问题,我特地在框架中留了混合查询和原生查询 目前EE提供的所有API可以覆盖实际开发中99%的需求,当极小概率下1%的需求无法覆盖时,您可以通过使用混合查询,也就是能支持的语句用EE生成,不能支持的语句就直接用RestHighLevelClient的语法,然后通过原生接口去完成查询,既简单有省事.当然如果您不喜欢这种"油电混动"的方式,您也可以直接用原生查询接口去完成查询,和直接使用RestHighLevelClient一样. 当然如果您实在不想用EE提供的任何方法,EE仍可以作为一个自动配置版的RestHighLevelClient使用,直接在需要的地方注入RestHighLevelClient进行使用即可,EE已经帮您把RestHighLevelClient按照您在配置文件中指定配置,自动装配成SpringBean了,所以在任何情况下,您都可以很自信很从容,就像直接使用官方的RestHighLevelClient一样,根本不需要担心有一天出问题了怎么办,大不了不用EE,只把它当成一个引入依赖和自动配置的工具.而且这种可能性也非常的低,我们还有专门的答疑群无偿在线给予您支持,对您的合理需求也会第一时间响应并安排落地. EE对所有项目透明,代码零侵入,引入不影响您当前项目的所有功能,引入后您依旧可以使用RestHighLevelClient全部功能,并且可以享受到EE为您提供的各种开箱即用的功能和解放双手的智能化套件

八，接入优势

• 简单易用高效不用我多说了吧,MyBatis-Plus用户懂的都懂! 大把的时间节省出来,做...爱做的事情,真香!
• 使用门槛降低,就算是刚不懂Es的小白,也可以用EE开发各种功能
• 大幅减少代码量,提升代码可读性,降低重复代码量,提升代码质量
• 专业答疑团队,无忧售后
• 永久免费

九，避坑指南

1，ES版本及SpringBoot版本

由于我们底层用了ES官方的RestHighLevelClient,所以对ES版本有要求,要求ES和RestHighLevelClient JAR依赖版本必须为7.14.0,至于es客户端,实际 测下来7.X任意版本都可以很好的兼容.

值得注意的是,由于SpringData-ElasticSearch的存在,Springboot它内置了和ES及RestHighLevelClient依赖版本,这导致了不同版本的Springboot实际引入的ES及RestHighLevelClient 版本不同,而ES官方的这两个依赖在不同版本间的兼容性非常差,进一步导致很多用户无法正常使用Easy-Es,抱怨我们框架有缺陷,实际上这只是一个依赖冲突的问题. 我们在项目启动时做了依赖校验,如果您的项目在启动时可以在控制台看到打印出级别为Error且内容为"Easy-Es supported elasticsearch and restHighLevelClient jar version is:7.14.0 ,Please resolve the dependency conflict!" 的日志时,则说明有依赖冲突待您解决. 解决方案其实很简单,可以像下面一样配置maven的exclude移除Springboot或Easy-Es已经声明的ES及RestHighLevelClient依赖,然后重新引入,引入时指定版本号为7.14.0即可解决.

        
            org.springframework.boot
            spring-boot-starter-web
            
                
                    org.elasticsearch.client
                    elasticsearch-rest-high-level-client
                
                
                    org.elasticsearch.client
                    elasticsearch-rest-client
                
                
                    org.elasticsearch
                    elasticsearch
                
            
        
        
            org.elasticsearch.client
            elasticsearch-rest-high-level-client
            7.14.0
        
        
            org.elasticsearch.client
            elasticsearch-rest-client
            7.14.0
        
        
            org.elasticsearch
            elasticsearch
            7.14.0
        

也可以简单粗暴的把springboot版本调整到2.5.5,其它都不需要调整,也可以勉强正常使用.

2，ES索引的keyword类型和text类型以及termQuery,match,match_phrase区别

 ES中的keyword类型,和MySQL中的字段基本上差不多,当我们需要对查询字段进行精确匹配,左模糊,右模糊,全模糊,排序聚合等操作时,需要该字段的索引类型为keyword类型,否则你会发现查询没有查出想要的结果,甚至报错. 比如EE中常用的API eq(),like(),distinct()等都需要字段类型为keyword类型.

当我们需要对字段进行分词查询时,需要该字段的类型为text类型,并且指定分词器(不指定就用ES默认分词器,效果通常不理想). 比如EE中常用的API match()等都需要字段类型为text类型. 当使用match查询时未查询到预期结果时,可以先检查索引类型,然后再检查分词器,因为如果一个词没被分词器分出来,那结果也是查询不出来的.

当同一个字段,我们既需要把它当keyword类型使用,又需要把它当text类型使用时,此时我们的索引类型为keyword_text类型,EE中不指定字段类型时,则默认该字段类型为此keyword+text双类型,双类型如下图所示,值得注意的是,当我们把该字段当做keyword类型查询时,ES要求传入的字段名称为"字段名.keyword",当把该字段当text类型查询时,直接使用原字段名即可. 值得庆幸的是,自2.0版本起,框架内部对此作了处理,默认会根据当前字段的索引类型和查询的类型来决定实际到底使用哪种类型,.keyword后缀框架会自动拼接,进一步减少了小白踩此坑的可能,如果您不希望框架自动根据上下文拼接.keyword后缀,您也可以通过配置文件关闭此项智能化功能, easy-es.global-config.db-config.smartAddKeywordSuffix=false

 3，字段id

由于框架很多功能都是借助id实现的,比如selectById,update,deleteById...,而且ES中也必须有一列作为数据id,因此我们强制要求用户封装的实体类中包含字段id列,否则框架不少功能无法正常使用.

public class Document {
    /**
     * es中的唯一id,如果你想自定义es中的id为你提供的id,比如MySQL中的id,请将注解中的type指定为customize或直接在全局配置文件中指定,如此id便支持任意数据类型)
     */
    @TableId(type = IdType.CUSTOMIZE)
    private String id;
}

如果不添加@TableId注解或者添加了注解但未指定type,则id默认为es自动生成的id.

在调用insert方法时,如果该id数据在es中不存在,则新增该数据,如果已有该id数据,则即便你调用的是insert方法,实际上的效果也是更新该id对应的数据,这点需要区别于MP和MySQL

4，项目中同时使用Mybatis-Plus和Easy-Es

在此场景下,您需要将MP的mapper和EE的mapper分别放在不同的目录下,并在配置扫描路径时各自配各自的扫描路径,如此便可共存使用了,否则两者在SpringBoot启动时都去扫描同一路径,并尝试注册为自己的bean,由于底层实现依赖的类完全不一样,所以会导致其中之一注册失败,整个项目无法正常启动.可参考下图:

 

 快速开始

一，环境准备

• 拥有 Java 开发环境以及相应 IDE
• 熟悉MySQL
• 熟悉 Spring Boot (推荐版本2.5.x +)
• 熟悉 Maven
• 了解Es基本概念或已读避坑指南 (强烈推荐)
• 已安装Es 推荐7.x版本(没有安装的可自行百度教程,建议再装一个es-head插件,便于可视化验证),低版本可能存在API不兼容或其它未知情况,因为底层采用RestHighLevelClient而非RestLowLevelClient,本Demo采用Es版本为7.14.0

特别注意

由于springboot内置关联了es版本,不同的springboot版本会导致实际项目中引入的es依赖版本过低或过高, 而es不同版本兼容性比较差,很多用户踩到一些因依赖冲突而导致兼容问题的坑,在此特地提醒用户,如果您项目实际依赖的es版本不为 7.14.0版本,我们强烈建议您显示指定es依赖jar包版本为7.14.0,与我们底层使用的es依赖版本保持一致,如此兼容性最佳, 不易踩坑. 底层之所以采用7.14.0也是经过多方调研,选择了一个稳定无安全漏洞的版本,经墨菲扫描该版本安全可靠. 至于ES客户端版本,7.10+实测兼容性都非常出色,依赖中的jar包版本与客户端版本不匹配无妨,重点是依赖的Jar版本

二，初始化工程

1，创建一个空的 Spring Boot 工程

添加依赖

        
        
            org.dromara.easy-es
            easy-es-boot-starter
            
            Latest Version
        

        
        
            org.springframework.boot
            spring-boot-starter-web
            
                
                    org.elasticsearch.client
                    elasticsearch-rest-high-level-client
                
                
                    org.elasticsearch
                    elasticsearch
                
            
        
        
            org.elasticsearch.client
            elasticsearch-rest-high-level-client
            7.14.0
        
        
            org.elasticsearch
            elasticsearch
            7.14.0
        

配置

在 application.yml 配置文件中添加EasyEs必须的相关配置：

easy-es:
  enable: true #默认为true,若为false则认为不启用本框架
  address : 127.0.0.1:9200 # es的连接地址,必须含端口 若为集群,则可以用逗号隔开 例如:127.0.0.1:9200,127.0.0.2:9200
  username: elastic #若无 则可省略此行配置
  password: WG7WVmuNMtM4GwNYkyWH #若无 则可省略此行配置

其它配置暂可省略,后面有章节详细介绍EasyEs的配置

在 Spring Boot 启动类中添加 @EsMapperScan 注解，扫描 Mapper 文件夹：

@SpringBootApplication
@EsMapperScan("com.xpc.easyes.sample.mapper")
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

需求

现有一张Document文档表，随着数据量膨胀,其查询效率已经无法满足产品需求,其表结构如下,我们打算将此表内容迁移至Es搜索引擎,提高查询效率

 编码

编写实体类Document.java

@Data
public class Document {
    /**
     * es中的唯一id
     */	
    private String id;
    /**
     * 文档标题
     */
    private String title;
    /**
     * 文档内容
     */
    private String content;
}

温馨提示

• 上面字段名称以及下划线转自动驼峰,字段在ES中的存储类型,分词器等均可配置,在后续章节会有介绍.
• String类型默认会被EE创建为keyword类型,keyword类型支持精确查询等
• 如需分词查询,可像上面content一样,在字段上加上@TableField注解并指明字段类型为text,并指定分词器.

编写Mapper类 DocumentMapper.java

public interface DocumentMapper extends BaseEsMapper {
}

前置操作

手动创建索引(相当于MySQL等数据库中的表),有了索引才能进行后续CRUD操作.

    @Test
    public void testCreateIndex() {
        // 测试创建索引,框架会根据实体类及字段上加的自定义注解一键帮您生成索引 需确保索引托管模式处于manual手动挡(默认处于此模式),若为自动挡则会冲突
        boolean success = documentMapper.createIndex();
        Assertions.assertTrue(success);
    }

温馨提示

• 我们目前提供了4种索引创建的方式,上述演示的是推荐新手使用的一键创建模式,如果您对其它集中模式感兴趣,可以移步至索引托管章节查看
• 其中自动挡模式之平滑模式可以自动感知索引变化,自动调整索引,平滑迁移数据,但不推荐小白使用,建议了解原理及源码后再使用
• 当然您也可以通过其它几种模式来维护索引,或者通过logstash,es-head等工具进行索引维护

开始使用(CRUD)

新增一条数据(相当于MySQL中的Insert操作)

    @Test
    public void testInsert() {
        // 测试插入数据
        Document document = new Document();
        document.setTitle("老汉");
        document.setContent("推*技术过硬");
        int successCount = documentMapper.insert(document);
        System.out.println(successCount);
    }

根据条件查询指定数据(相当于MySQL中的Select操作)

    @Test
    public void testSelect() {
        // 测试查询 写法和MP一样 可以用链式,也可以非链式 根据使用习惯灵活选择即可
        String title = "老汉";
        Document document = EsWrappers.lambdaChainQuery(documentMapper)
                 .eq(Document::getTitle, title)
                 .one();
        System.out.println(document);
        Assert.assertEquals(title,document.getTitle());
    }

更新数据(相当于MySQL中的Update操作)

    @Test
    public void testUpdate() {
        // 测试更新 更新有两种情况 分别演示如下:
        // case1: 已知id, 根据id更新 (为了演示方便,此id是从上一步查询中复制过来的,实际业务可以自行查询)
        String id = "krkvN30BUP1SGucenZQ9";
        String title1 = "隔壁老王";
        Document document1 = new Document();
        document1.setId(id);
        document1.setTitle(title1);
        documentMapper.updateById(document1);

        // case2: id未知, 根据条件更新
        LambdaEsUpdateWrapper wrapper = new LambdaEsUpdateWrapper<>();
        wrapper.eq(Document::getTitle,title1);
        Document document2 = new Document();
        document2.setTitle("隔壁老李");
        document2.setContent("推*技术过软");
        documentMapper.update(document2,wrapper);

        
    }

删除数据(相当于MySQL中的Delete操作)

    @Test
    public void testDelete() {
        // 测试删除数据 删除有两种情况:根据id删或根据条件删
        // 鉴于根据id删过于简单,这里仅演示根据条件删,以老李的名义删,让老李心理平衡些
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        String title = "隔壁老李";
        wrapper.eq(Document::getTitle,title);
        int successCount = documentMapper.delete(wrapper);
        System.out.println(successCount);
    }

三，springboot集成Easy-ES

1，创建springboot项目，pom文件添加Easy-ES依赖

    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.6.0
         
    
    com.example
    ee-use
    0.0.1-SNAPSHOT
    ee-use
    Demo project for Spring Boot
    
        1.8
    
    
        
        
            org.springframework.boot
            spring-boot-starter-web
            
                
                    org.elasticsearch.client
                    elasticsearch-rest-high-level-client
                
                
                    org.elasticsearch
                    elasticsearch
                
            
        
        
            org.elasticsearch.client
            elasticsearch-rest-high-level-client
            7.14.0
        
        
            org.elasticsearch
            elasticsearch
            7.14.0
        

        
            org.dromara.easy-es
            easy-es-boot-starter
            
            ${Latest version}
        

        
            org.springframework.boot
            spring-boot-starter-test
            test
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

特别注意 当前发行的最新版本Latest version请看上图获取,实际填入的是具体的版本号数字,比如2.0.0,并不是Latest version!!!

另外由于springboot内置关联了es版本,不同的springboot版本会导致实际项目中引入的es依赖版本过低或过高, 而es不同版本兼容性比较差,很多用户踩到一些因依赖冲突而导致兼容问题的坑,在此特地提醒用户,如果您项目实际依赖的es版本不为 7.14.0版本,我们强烈建议您显示指定es依赖jar包版本为7.14.0,与我们底层使用的es依赖版本保持一致,如此兼容性最佳, 不易踩坑. 底层之所以采用7.14.0也是经过多方调研,选择了一个稳定无安全漏洞的版本,经墨菲扫描该版本安全可靠. 至于ES客户端版本,7.10+实测兼容性都非常出色,依赖中的jar包版本与客户端版本不匹配无妨,重点是依赖的Jar版本

1，核心代码

@RestController
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class TestUseEeController {
    private final DocumentMapper documentMapper;

    @GetMapping("/createIndex")
    public Boolean createIndex() {
        // 1.初始化-> 创建索引(相当于mysql中的表)
        return documentMapper.createIndex();
    }

    @GetMapping("/insert")
    public Integer insert() {
        // 2.初始化-> 新增数据
        Document document = new Document();
        document.setTitle("老汉");
        document.setContent("推*技术过硬");
        return documentMapper.insert(document);
    }

    @GetMapping("/search")
    public List search() {
        // 3.查询出所有标题为老汉的文档列表
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉");
        return documentMapper.selectList(wrapper);
    }
}

2，启动及使用

添加配置信息

easy-es:
  enable: true # 默认为true,若为false时,则认为不启用本框架
  address: 127.0.0.0:9200  #填你的es连接地址
  # username: 有设置才填写,非必须
  # password: 有设置才填写,非必须

启动项目

使用

依次请求下述三个接口:

http://localhost:8080/createIndex (opens new window)(创建索引)

http://localhost:8080/insert (opens new window)(插入数据)

http://localhost:8080/search (opens new window)(查询)

3，配置

基础配置:

如果缺失可导致项目无法正常启动,其中账号密码可缺省.

easy-es:
  address : 127.0.0.1:9200 # es连接地址+端口 格式必须为ip:port,如果是集群则可用逗号隔开
  username: elastic #如果无账号密码则可不配置此行
  password: WG7WVmuNMtM4GwNYkyWH #如果无账号密码则可不配置此行 

扩展配置

可缺省,不影响项目启动,为了提高生产环境性能,建议您按需配置

特别注意

如果您开启了索引托管-平滑模式(默认开启),并且您需要迁移的数据量很大,可以调大socketTimeout,否则迁移可能会超时异常 单位是毫秒,默认为1分钟,我们经过测试发现迁移1万条数据大约需要5秒左右,当然该数值需要综合考虑您的服务器硬件负载等因素,因此建议 您按需配置,尽量给大不给小,跟那玩意一样,大点没事,太小你懂的!

easy-es:
  keep-alive-millis: 30000 # 心跳策略时间 单位:ms
  connect-timeout: 5000 # 连接超时时间 单位:ms
  socket-timeout: 600000 # 通信超时时间 单位:ms 
  request-timeout: 5000 # 请求超时时间 单位:ms
  connection-request-timeout: 5000 # 连接请求超时时间 单位:ms
  max-conn-total: 100 # 最大连接数 单位:个
  max-conn-per-route: 100 # 最大连接路由数 单位:个

全局配置:

easy-es:
  enable: true # 是否开启EE自动配置 默认开启,可缺省
  schema: http # 默认为http 可缺省
  banner: true # 默认为true 打印banner 若您不期望打印banner,可配置为false
  global-config:
    process-index-mode: manual #索引处理模式,smoothly:平滑模式, not_smoothly:非平滑模式, manual:手动模式,,默认开启此模式
    print-dsl: true # 开启控制台打印通过本框架生成的DSL语句,默认为开启,测试稳定后的生产环境建议关闭,以提升少量性能
    distributed: false # 当前项目是否分布式项目,默认为true,在非手动托管索引模式下,若为分布式项目则会获取分布式锁,非分布式项目只需synchronized锁.
    reindexTimeOutHours: 72 # 重建索引超时时间 单位小时,默认72H 可根据ES中存储的数据量调整
    async-process-index-blocking: true # 异步处理索引是否阻塞主线程 默认阻塞 数据量过大时调整为非阻塞异步进行 项目启动更快
    active-release-index-max-retry: 4320 # 分布式环境下,平滑模式,当前客户端激活最新索引最大重试次数,若数据量过大,重建索引数据迁移时间超过4320/60=72H,可调大此参数值,此参数值决定最大重试次数,超出此次数后仍未成功,则终止重试并记录异常日志
    active-release-index-fixed-delay: 60 # 分布式环境下,平滑模式,当前客户端激活最新索引最大重试次数 分布式环境下,平滑模式,当前客户端激活最新索引重试时间间隔 若您期望最终一致性的时效性更高,可调小此值,但会牺牲一些性能
    
    db-config:
      map-underscore-to-camel-case: false # 是否开启下划线转驼峰 默认为false
      index-prefix: daily_ # 索引前缀,可用于区分环境  默认为空 用法和MP的tablePrefix一样的作用和用法
      id-type: customize # id生成策略 customize为自定义,id值由用户生成,比如取MySQL中的数据id,如缺省此项配置,则id默认策略为es自动生成
      field-strategy: not_empty # 字段更新策略 默认为not_null
      enable-track-total-hits: true # 默认开启,开启后查询所有匹配数据,若不开启,会导致无法获取数据总条数,其它功能不受影响,若查询数量突破1W条时,需要同步调整@IndexName注解中的maxResultWindow也大于1w,并重建索引后方可在后续查询中生效(不推荐,建议分页查询).
      refresh-policy: immediate # 数据刷新策略,默认为不刷新,若对数据时效性要求比较高,可以调整为immediate,但性能损耗高,也可以调整为折中的wait_until
      batch-update-threshold: 10000 # 批量更新接口的阈值 默认值为1万,突破此值需要同步调整enable-track-total-hits=true,@IndexName.maxResultWindow > 1w,并重建索引.
      smartAddKeywordSuffix: true # 是否智能为字段添加.keyword后缀 默认开启,开启后会根据当前字段的索引类型及当前查询类型自动推断本次查询是否需要拼接.keyword后缀

其它配置:

logging:
  level:
   tracer: trace # 开启trace级别日志,在开发时可以开启此配置,则控制台可以打印es全部请求信息及DSL语句,为了避免重复,开启此项配置后,可以将EE的print-dsl设置为false.

温馨提示

• id-type支持3种类型:

  • auto: 由ES自动生成,是默认的配置,无需您额外配置 推荐
  • uuid: 系统生成UUID,然后插入ES (不推荐)
  • customize: 用户自定义,在此类型下,用户可以将任意数据类型的id存入es作为es中的数据id,比如将mysql自增的id作为es的id,可以开启此模式,或通过@TableId(type)注解指定.

• field-strategy支持3种类型:

  • not_null: 非Null判断,字段值为非Null时,才会被更新
  • not_empty: 非空判断,字段值为非空字符串时才会被更新
  • ignore: 忽略判断,无论字段值为什么,都会被更新
  • 在配置了全局策略后,您仍可以通过注解针对个别类进行个性化配置,全局配置的优先级是小于注解配置的

• refresh-policy支持3种策略

  • none: 默认策略,不刷新数据
  • immediate : 立即刷新,会损耗较多性能,对数据实时性要求高的场景下适用
  • wait_until: 请求提交数据后，等待数据完成刷新(1s)，再结束请求 性能损耗适中

4，注解

@EsMapperScan

• 描述：mapper扫描注解,功能与MP的@MapperScan一致

• 使用位置：Springboot启动类

• @EsMapperScan("cn.easy-es-mapper")
  public class Application{
      // 省略其它...
  }
  

  

   温馨提示

  由于EE和MP对Mapper的扫描都是采用Springboot的doScan，而且两套系统互相独立，所以在扫描的时候没有办法互相隔离,因此如果您的项目同时有用到EE和MP，您需要将EE的Mapper和MP的Mapper放在不同的包下，否则项目将无法正常启动

@IndexName

• 描述：索引名注解，标识实体类对应的索引 对应MP的@TableName注解,在v0.9.40之前此注解为@TableName.

• 使用位置：实体类

• @IndexName
  public class Document {
      // 省略其它字段
  }
  

  属性	类型	必须指定	默认值	描述
  value	String	否	""	索引名，可简单理解为MySQL表名
  shardsNum	int	否	1	索引分片数
  replicasNum	int	否	1	索引副本数
  aliasName	String	否	""	索引别名
  keepGlobalPrefix	boolean	否	false	是否保持使用全局的 tablePrefix 的值，与MP用法一致
  child	boolean	否	false	是否子文档
  childClass	Class	否	DefaultChildClass.class	父子文档-子文档类
  maxResultWindow	int	否	10000	分页返回的最大数据量,默认值为1万条,超出推荐使用searchAfter或滚动查询等方式,详见拓展功能章节. 当此值调整至大于1W后,需要重建索引并同步开启配置文件中的enable-track-total-hits=true方可生效
  routing	String	否	""	路由,CRUD作用的路由
  refreshPolicy	Enum	否	NONE	索引数据刷新策略,默认为不刷新,其取值参考RefreshPolicy枚举类,一共有3种刷新策略

  动态索引名称支持 如果你的索引名称是不固定的,我们提供了两种方式可修改CRUD时的索引名称

  调用mapper.setCurrentActiveIndex(String indexName)方法,此处的mapper为你自定义的mapper,如documentMapper,通过此API修改索引名称后,全局生效.

  在对应的参数中指定当前操作作用的索引,例如 wrapper.index(String indexName),通过此API修改索引名称后,仅作用于该wrapper对应的操作,粒度最细.

温馨提示

• 当您想直接把类名当作索引名，且并不需要对索引进行其它配置时，可省略此注解
• 通过注解指定的索引名称优先级最高,指定了注解索引,则全局配置和自动生成索引不生效,采用注解中指定的索引名称. 优先级排序: 注解索引>全局配置索引前缀>自动生成
• keepGlobalPrefix选项,(0.9.4+版本才支持)默认值为false,是否保持使用全局的 indexPrefix 的值:
  • 既配置了全局tablePrefix,@TableName注解又指定了value值时,此注解选项才会生效,如果其值为true,则框架最终使用的索引名称为:全局indexPrefix+此注解的value,例如:dev_document
  • 此注解选项用法和MP中保持一致.
• 其中shardNum为分片数,replicasNum为副本数,如果不指定,默认值均为1
• RefreshPolicy 数据刷新策略
  • None 不刷新,es默认的策略,此策略下数据变更后有一定延迟才会生效,但写入性能最好,通常情况下使用此默认策略即可
  • IMMEDIATE 立即刷新,适用于对数据延迟敏感的业务场景,但消耗的系统资源最大
  • WAIT_UNTIL 请求提交数据后,等待数据完成刷新(约1s),再结束请求 性能损耗适中 属于折中方案

@IndexId

• 描述：ES主键注解
• 使用位置：实体类中被作为ES主键的字段, 对应MP的@TableId注解

public class Document {
    @IndexId
    private String id;
    // 省略其它字段
}

温馨提示

当您字段命名为id且类型为String时，且不需要采用UUID及自定义ID类型时，可省略此注解

由于es对id的默认名称做了处理(下划线+id):_id,所以EE已为您屏蔽这步操作,您无需在注解中指定,框架也会自动帮您完成映射.

• Id的生成类型支持以下几种:
  • IdType.NONE: 由ES自动生成,是默认缺省时的配置,无需您额外配置 推荐
  • IdType.UUID: 系统生成UUID,然后插入ES (不推荐)
  • IdType.CUSTOMIZE: 由用户自定义,用户自己对id值进行set,如果用户指定的id在es中不存在,则在insert时就会新增一条记录,如果用户指定的id在es中已存在记录,则自动更新该id对应的记录

@IndexField

• 描述：ES字段注解, 对应MP的@TableField注解
• 使用位置：实体类中被作为ES索引字段的字段
• 使用场景举例：

1. 实体类中的字段并非ES中实际的字段,比如把实体类直接当DTO用了,加了一些ES中并不存在的无关字段,此时可以标记此字段,以便让EE框架跳过此字段,对此字段不处理.
2. 字段的更新策略,比如在调用更新接口时,实体类的字段非Null或者非空字符串时才更新,此时可以加字段注解,对指定字段标记更新策略.
3. 需要对类型为text或keyword_tex字段聚合时,可指定其fieldData=true,否则es会报错.
4. 对指定字段进行自定义命名,比如该字段在es中叫wu-la,但在实体model中叫ula,此时可以在value中指定value="wu-la".
5. 在自动托管索引模式下,可指定索引分词器及索引字段类型.
6. 在自动托管索引模式下,可指定索引中日期的format格式.
7. 可指定创建索引时,自动对指定字段添加忽略大小写的配置.

使用示例:

public class Document {
    // 此处省略其它字段... 
        
    // 场景一:标记es中不存在的字段
    @IndexField(exist = false)
    private String notExistsField;
        
    // 场景二:更新时,此字段非空字符串才会被更新
    @IndexField(strategy = FieldStrategy.NOT_EMPTY)
    private String creator;
    
    // 场景三: 指定fieldData
    @IndexField(fieldType = FieldType.TEXT, fieldData = true)
    private String filedData;
    
    // 场景四:自定义字段名
    @IndexField("wu-la")    
    private String ula;

    // 场景五:支持日期字段在es索引中的format类型
    @IndexField(fieldType = FieldType.DATE, dateFormat = "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis")
    private String gmtCreate;

    // 场景六:支持指定字段在es索引中的分词器类型
    @IndexField(fieldType = FieldType.TEXT, analyzer = Analyzer.IK_SMART, searchAnalyzer = Analyzer.IK_MAX_WORD)
    private String content;
    
    // 场景七：支持指定字段在es的索引中忽略大小写,以便在term查询时不区分大小写,仅对keyword类型字段生效,es的规则,并非框架限制.
    @IndexField(fieldType = FieldType.KEYWORD, ignoreCase = true)
    private String caseTest;
}

属性	类型	必须指定	默认值	描述
value	String	否	""	字段名
exist	boolean	否	true	字段是否存在
fieldType	Enum	否	FieldType.NONE	字段在es索引中的类型
fieldData	boolean	否	false	text类型字段是否支持聚合
analyzer	String	否	Analyzer.NONE	索引文档时用的分词器
searchAnalyzer	String	否	Analyzer.NONE	查询分词器
strategy	Enum	否	FieldStrategy.DEFAULT	字段验证策略
dateFormat	String	否	""	es索引中的日期格式,如yyyy-MM-dd
nestedClass	Class	否	DefaultNestedClass.class	嵌套类
parentName	String	否	""	父子文档-父名称
childName	String	否	""	父子文档-子名称
joinFieldClass	Class	否	JoinField.class	父子文档-父子类型关系字段类
ignoreCase	boolean	否	false	keyword类型字段是否忽略大小写
ignoreAbove	int	否	256	字符串将被索引或存储的最大长度
scalingFactor	int	否	100	用于指定浮点数字段的缩放因子,scaled_float类型字段必须指定此参数,否则es创建索引报错

温馨提示

• 更新策略一共有3种:
  • NOT_NULL: 非Null判断,字段值为非Null时,才会被更新
  • NOT_EMPTY: 非空判断,字段值为非空字符串时才会被更新
  • IGNORE: 忽略判断,无论字段值为什么,都会被更新
• 针对BigDecimal类型字段,其scalingFactor若用户未指定,则系统默认值为100

其中场景四和场景五仅在索引自动托管模式下生效,如果开启了手动处理索引模式,则需要用户通过手动调用我提供的API传入相应的分词器及日期格式化参数进行索引的创建/更新

@MultiIndexField

• 描述：多字段注解
• 使用位置：实体类中单个字段期望用多种分词器或多种字段类型的字段上
• 使用场景举例：比如一个字段既想要用中文分词器查询,又想要用拼音分词器查询

属性	类型	必须指定	默认值	描述
mainIndexField	@IndexField	是	-	主字段必须指定,用法可以参考上面的@IndexField
InnerIndexField	@InnerIndexField[]	否	{}	内部字段,可以为空数组,当内部字段不指定时,则此注解降级为@IndexField,与@IndexField注解效果一致

@InnerIndexField

• 描述：内部字段注解
• 使用位置：@MultiIndexField内部
• 使用场景举例：比如一个字段既想要用中文分词器查询,又想要用拼音分词器查询,可以在@MultiIndexField中指定

属性	类型	必须指定	默认值	描述
suffix	String	是	-	内部字段后缀
fieldType	FieldType	是	-	内部字段的字段类型,此枚举与@IndexField中的FieldType是同一个,用法可以直接参考
analyzer	String	否	-	索引分词器,与@IndexField中的Analyzer是同一个,用法可直接参考
searchAnalyzer	String	否	-	查询分词器,与@IndexField中的Analyzer是同一个,用法可直接参考
ignoreAbove	int	否	256	内部字段,字符串将被索引或存储的最大长度

使用示例:

public class Document {
  /**
   * 复合字段,此注解和SpringData中的MultiField用法类似 适用于对同一个字段通过多种分词器检索的场景
   */
  @MultiIndexField(mainIndexField = @IndexField(fieldType = FieldType.KEYWORD),
          otherIndexFields = {@InnerIndexField(suffix = "zh", fieldType = FieldType.TEXT, analyzer = Analyzer.IK_SMART),
                  @InnerIndexField(suffix = "pinyin", fieldType = FieldType.TEXT, analyzer = Analyzer.PINYIN)})
  private String multiField;
}

查询示例:

    @Test
    public void testMultiFieldSelect() {
        // 药品 中文名叫葡萄糖酸钙口服溶液 英文名叫 Calcium Gluconate 汉语拼音为 putaotangsuangaikoufurongye
        // 用户可以通过模糊检索,例如输入 Calcium 或 葡萄糖 或 putaotang时对应药品均可以被检索到
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.match("english", "Calcium")
                .or()
                .match("multi_field.zh", "葡萄糖")
                .or()
                .match("multi_field.pinyin", "putaotang");
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
    }

上述使用案例中,开启了驼峰自动转下划线,因此字段名为"multi_field",实际上在查询中用户只需要用"字段名.suffix"组合,即可确定当前启用哪个内部字段,当查询主字段时,则无需指定suffix,直接字段名即可.

@HighLight

• 描述：高亮注解
• 使用位置：实体类中需要高亮的被查询字段
• 使用场景举例：比如输入关键词"老汉"进行查询,期望内容中包含"老汉"的部分被展示为红色或加粗

属性	类型	必须指定	默认值	描述
mappingField	String	否	""	高亮内容映射字段的名称,比如我想把高亮内容"老汉"赋值到字段pushCar上,就可以指定此属性值为pushCar
fragmentSize	int	否	100	高亮字段截取长度,默认为100
numberOfFragments	int	否	-1	搜索返回的高亮片段数量,默认全部返回
preTag	String	否	< em >	高亮标签,高亮内容将处于preTag之后
postTag	String	否	< /em >	高亮标签,高亮内容将处于postTag之前
highLightType	HighLightTypeEnum	否	UNIFIED	高亮类型

@Score

• 描述：得分注解
• 使用位置：实体类中被作为ES查询得分返回的字段
• 使用场景举例：比如需要知道本次匹配查询得分有多少时,可以在实体类中添加一个类型为Float/float的字段,并在该字段上添加@Score注解,在后续查询中,若es有返回当次查询的得分,则此得分会自动映射至此字段上

属性	类型	必须指定	默认值	描述
decimalPlaces	int	否	0	得分保留小数位,默认不处理,保持es返回的得分值

@Distance

• 描述：距离注解
• 使用位置：实体类中被作为ES地理位置排序距离值的返回字段
• 使用场景举例：比如需要知道按距离由近及远查询后的数据,实际距离某一坐标有多远,可以在实体类中添加一个类型为Double/double的字段,并在该字段上添加@Distance注解,在后续查询中,若es有返回距离,则此距离会自动映射至此字段上

属性	类型	必须指定	默认值	描述
decimalPlaces	int	否	0	距离保留小数位,默认不处理,保持es返回的距离值

其它注解

除了上面这几个高频注解，项目中偶尔还会用到一些其它注解，比如比如拦截器注解@Intercepts等注解，我们会在后面具体的章节详细介绍，此处仅列出几个必须掌握的注解，其它注解按需学习即可。

核心功能

一，条件构造器

1，介绍

Wrapper支持两种方式创建:

• 直接new,例如 new LambdaEsQueryWrapper<>().
• 通过EsWrappers.lambdaQuery()创建,可支撑链式编程的场景,对标MP的Wrappers

说明

• 以下出现的第一个入参boolean condition表示该条件是否加入最后生成的语句中，例如：query.like(StringUtils.isNotBlank(name), Entity::getName, name) .eq(age!=null && age >= 0, Entity::getAge, age)
• 以下代码块内的多个方法均为从上往下补全个别boolean类型的入参,默认为true
• 以下出现的泛型Param均为Wrapper的子类实例(均具有AbstractWrapper的所有方法)
• 以下方法在入参中出现的R为泛型,在普通wrapper中是String,在LambdaWrapper中是函数(例:Entity::getId,Entity为实体类,getId为字段id的getMethod)
• 以下方法入参中的R column均表示数据库字段,当R具体类型为String时则为数据库字段名(字段名是数据库关键字的自己用转义符包裹!)!而不是实体类数据字段名!!!,另当R具体类型为SFunction时项目runtime不支持eclipse自家的编译器!!!
• 以下举例均为使用普通wrapper,入参为Map和List的均以json形式表现!
• 使用中如果入参的Map或者List为空,则不会加入最后生成的sql中!

警告

不支持以及不赞成在 RPC 调用中把 Wrapper 进行传输

1. wrapper 很重
2. 传输 wrapper 可以类比为你的 controller 用 map 接收值(开发一时爽,维护火葬场)
3. 正确的 RPC 调用姿势是写一个 DTO 进行传输,被调用方再根据 DTO 执行相应的操作
4. 我们拒绝接受任何关于 RPC 传输 Wrapper 报错相关的 issue 甚至 pr

AbstractWrapper

说明

QueryWrapper(LambdaEsQueryWrapper) 和 UpdateWrapper(LambdaEsUpdateWrapper) 的父类用于生成 语句 的 where 条件, entity 属性也用于生成 语句 的 where 条件注意: entity 生成的 where 条件与 使用各个 api 生成的 where 条件 没有任何关联行为

QueryWrapper

说明

继承自 AbstractWrapper ,自身的内部属性 entity 也用于生成 where 条件及 LambdaEsQueryWrapper

UpdateWrapper

说明

继承自 AbstractWrapper ,自身的内部属性 entity 也用于生成 where 条件及 LambdaEsUpdateWrapper

 AbstractChainWrapper

说明

继承自 Wrapper ,用于支持链式调用

 2，索引条件构造器

LambdaEsIndexWrapper

提示

索引的CRUD中的相关条件依托于此构造器进行封装

API说明

LambdaEsIndexWrapper提供了下述API可供用户使用

    mapping(R column, FieldType fieldType);
    mapping(R column, FieldType fieldType, Boolean fieldData);
    mapping(R column, FieldType fieldType, Float boost);
    mapping(R column, FieldType fieldType, Boolean fieldData, Float boost);
    mapping(R column, FieldType fieldType, String dateFormat);
    mapping(R column, FieldType fieldType, String analyzer, String searchAnalyzer);
    mapping(R column, FieldType fieldType, String analyzer, String searchAnalyzer, String dateFormat);
    mapping(R column, FieldType fieldType, String analyzer, String searchAnalyzer, Float boost);
    mapping(R column, FieldType fieldType, String analyzer, String searchAnalyzer, String dateFormat, Boolean fieldData, Float boost);
    mapping(Map mapping);
    
    createAlias(String aliasName);
    settings(Settings settings);
    settings(Integer shards, Integer replicas);
    maxResultWindow(Integer maxResultWindow);
    indexName(String... indexNames);

使用案例

    /**
     * LambdaEsIndexWrapper构造器使测案例一:创建索引,通过开箱即用的方法创建
     */
    @Test
    public void testCreateIndex() {
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        // 此处简单起见 索引名称须保持和实体类名称一致,字母小写 后面章节会教大家更如何灵活配置和使用索引
        wrapper.indexName(Document.class.getSimpleName().toLowerCase());

        // 此处将文章标题映射为keyword类型(不支持分词),文档内容映射为text类型(支持分词查询)
        wrapper.mapping(Document::getTitle, FieldType.KEYWORD, 2.0f)
                .mapping(Document::getLocation, FieldType.GEO_POINT)
                .mapping(Document::getGeoLocation, FieldType.GEO_SHAPE)
                .mapping(Document::getContent, FieldType.TEXT, Analyzer.IK_SMART, Analyzer.IK_MAX_WORD);
        
        // 设置分片及副本信息,可缺省
        wrapper.settings(3, 2);

        // 设置别名信息,可缺省
        String aliasName = "daily";
        wrapper.createAlias(aliasName);

        // 设置父子信息,若无父子文档关系则无需设置
        wrapper.join("joinField", "document", "comment");

        // 创建索引
        boolean isOk = documentMapper.createIndex(wrapper);
        Assertions.assertTrue(isOk);
    }

    /**
     * LambdaEsIndexWrapper构造器使测案例二:创建索引,通过自定义map 最难用但也最灵活
     */
    @Test
    public void testCreateIndexByMap() {
        // 演示通过自定义map创建索引,最为灵活,若方案一不能满足时可用此方法
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        wrapper.indexName(Document.class.getSimpleName().toLowerCase());
        wrapper.settings(3, 2);
        Map map = new HashMap<>();
        Map prop = new HashMap<>();
        Map field = new HashMap<>();
        field.put("type", FieldType.KEYWORD.getType());
        prop.put("this_is_field", field);
        map.put("properties", prop);
        wrapper.mapping(map);
        boolean isOk = documentMapper.createIndex(wrapper);
        Assertions.assertTrue(isOk);
    }

    /**
     * LambdaEsIndexWrapper构造器使测案例三:更新索引(不推荐使用,因为索引变动ES会重建索引,有其它更好的方式,可参考后面索引托管章节)
     */
    @Test
    public void testUpdateIndex() {
        // 测试更新索引
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        // 指定要更新哪个索引
        String indexName = Document.class.getSimpleName().toLowerCase();
        wrapper.indexName(indexName);
        wrapper.mapping(Document::getCreator, FieldType.KEYWORD);
        wrapper.mapping(Document::getGmtCreate, FieldType.DATE);
        boolean isOk = documentMapper.updateIndex(wrapper);
        Assertions.assertTrue(isOk);
    }

3，查询条件构造器

LambdaEsQueryWrapper

提示

此条件构造器主要用于查询数据时所需查询条件的封装

allEq

allEq(Map params)

全部eq

个别参数说明

params : key为数据库字段名,value为字段值

• 例: allEq({id:1,name:"老王",age:18})--->id = 1 and name = '老王' and age = 18

        

allEq(BiPredicate filter, Map params)

个别参数说明

filter : 过滤函数,是否允许字段传入比对条件中 params 与 null2IsNull : 同上

• 例: allEq((k,v) -> k.indexOf("a") >= 0, {id:1,name:"老王",age:18})--->name = '老王' and age = 18

eq

eq(R column, Object val)
eq(boolean condition, R column, Object val)

• 等于 =
• 例: eq("name", "老王")--->name = '老王'

gt

gt(R column, Object val)
gt(boolean condition, R column, Object val)

• 大于 >
• 例: gt("age", 18)--->age > 18

ge

ge(R column, Object val)
ge(boolean condition, R column, Object val)

• 大于等于 >=
• 例: ge("age", 18)--->age >= 18

lt

lt(R column, Object val)
lt(boolean condition, R column, Object val)

• 小于 <
• 例: lt("age", 18)--->age < 18

le

le(R column, Object val)
le(boolean condition, R column, Object val)

• 小于等于 <=
• 例: le("age", 18)--->age <= 18

between

between(R column, Object val1, Object val2)
between(boolean condition, R column, Object val1, Object val2)

• BETWEEN 值1 AND 值2
• 例: between("age", 18, 30)--->age between 18 and 30

like

like(R column, Object val)
like(boolean condition, R column, Object val)

• LIKE '%值%'
• 例: like("name", "王")--->name like '%王%'

likeLeft

likeLeft(R column, Object val)
likeLeft(boolean condition, R column, Object val)

• LIKE '%值'
• 例: likeLeft("name", "王")--->name like '%王'

likeRight

likeRight(R column, Object val)
likeRight(boolean condition, R column, Object val)

• LIKE '值%'
• 例: likeRight("name", "王")--->name like '王%'

isNotNull

isNotNull(R column)
isNotNull(boolean condition, R column)

• 字段 IS NOT NULL
• 例: isNotNull(Document::getTitle)--->title is not null

exists

exists(R column)
exists(boolean condition, R column)

效果和功能等价于上面的isNotNull,主要是为了照顾es原生语法习惯的用户

in

in(R column, Collection value)
in(boolean condition, R column, Collection value)

• 字段 in (value.get(0), value.get(1), ...)
• 例: in("age",{1,2,3})--->age in (1,2,3)

in(R column, Object... values)
in(boolean condition, R column, Object... values)

• 字段 in (v0, v1, ...)
• 例: in("age", 1, 2, 3)--->age in (1,2,3)

groupBy

groupBy(R... columns)
groupBy(boolean condition, R... columns)

• 分组：GROUP BY 字段, ...
• 例: groupBy(Document::getId,Document::getTitle)--->group by id,title

orderByDesc

orderByDesc(R... columns)
orderByDesc(boolean condition, R... columns)

• 排序：ORDER BY 字段, ... DESC
• 例: orderByDesc(Document::getId,Document::getTitle)--->order by id DESC,title DESC

limit

limit(Integer n);

limit(Integer m, Integer n);

• limit n 最多返回多少条数据,相当于MySQL中limit n 中的n,用法一致.
• limit m,n 跳过m条数据,最多返回n条数据,相当于MySQL中的limit m,n 或 offset m limit n
• 例: limit(10)--->最多只返回10条数据
• 例: limit(2,5)--->跳过前2条数据,从第3条开始查询,总共查询5条数据

温馨提示

n参数若不指定,则其默认值是10000 ,如果你单次查询超过1W条,建议采用分页(参考后面分页章节),万不得已非要在这里指定超过1w,比如指定2w,需要在查询的实体类上加上注解@IndexName(maxResultWindow=20000) 指定其maxResultWindow,并重建索引,否则es会报错,这是es的规则,它作此限制应该是为了保护你的内存防止溢出. 如果你单次查询,不想要太多得分较低的数据,需要手动指定n去做限制. 另外此参数作用与Es中的size,from一致,只是为了兼容MySQL语法而引入,使用者可以根据自身习惯二选一,当两种都用时,只有一种会生效,后指定的会覆盖先指定的

from

from(Integer from)

• 从第几条数据开始查询,相当于MySQL中limit (m,n)中的m.
• 例: from(10)--->从第10条数据开始查询

size

size(Integer size)

• 最多返回多少条数据,相当于MySQL中limit (m,n)中的n 或limit n 中的n
• 例: size(10)--->最多只返回10条数据

温馨提示

如果你单次查询,不想要太多得分较低的数据,需要手动指定size去做限制

minScore

minScore(Float score)

• 查询得分不低于score的数据,如果得分低于此值,则不被命中

trackScores

trackScores();

• 开启计算得分 默认值为关闭状态 查询得分可以用于排序等场景

index

index(String indexName)
index(boolean condition, String indexName)

温馨提示

可通过wrapper.index(String indexName)指定本次查询作用于哪个索引,如果本次查询要从多个索引上查询,那么索引名称可以用逗号隔开,例如wrapper.index("index1","indexe2"...) wrapper中指定的索引名称优先级最高,如果不指定则取实体类中配置的索引名称,如果实体类也未配置,则取实体名称小写作为当前查询的索引名 针对insert/delete/update等接口中无wrapper的情况,如果你需要指定索引名,可直接在对应接口的入参中添加索引名称,可参考下面示例:

    Document document = new Document();
    // 省略为document赋值的代码
    String indexName = "laohan";
    insert(document,indexName);

and

and(Consumer consumer)
and(boolean condition, Consumer consumer)

• AND
• 例: and(i -> i.eq(Document::getTitle, "Hello").eq(Document::getCreator, "Guy"))--->and (title ='Hello' and creator = 'Guy' )

or

or()
or(boolean condition)

• 拼接 OR 注意事项: 主动调用or表示紧接着下一个方法不是用and连接!(不调用or则默认为使用and连接)
• 例: eq("Document::getId",1).or().eq(Document::getTitle,"Hello")--->id = 1 or title ='Hello'

or(Consumer consumer)
or(boolean condition, Consumer consumer)

• 嵌套 OR

• 例: or(i -> i.eq(Document::getTitle, "Hello").ne(Document::getCreator, "Guy"))--->or (title ='Hello' and status != 'Guy' )

• 特殊情况

• 例: eq(Document::getTitle,"Hello") .and(i->i.eq(Document::getCreator,"Bob").or().eq(Document::getCreator,"Tom"))---> title="Hello" and(creator="Bob" or creator="Tom")

filter

and和filter的选择,它们在功能上类似,都是表示必须满足的条件,不同之处在于filter不计算得分,性能表现更好,但不支持根据得分排序.

filter()
filter(boolean condition)

• 拼接 filter 注意事项: 主动调用filter表示紧接着下一个方法不是用and连接!(不调用filter则默认为使用and连接)
• 例: eq("Document::getId",1).filter().eq(Document::getTitle,"Hello")--->id = 1 and title ='Hello'

filter(Consumer consumer)
filter(boolean condition, Consumer consumer)

• 嵌套 filter
• 例: filter(i -> i.eq(Document::getTitle, "Hello").eq(Document::getCreator, "Guy"))--->or (title ='Hello' and status = 'Guy' )

not

not()
not(boolean condition)

• 拼接 not 注意事项: 主动调用not表示紧接着下一个方法不是用and连接!(不调用not则默认为使用and连接)
• 例: eq("Document::getId",1).not().eq(Document::getTitle,"Hello")--->id = 1 and title !='Hello'

4，更新条件构造器

LambdaEsUpdateWrapper

此条件构造器主要用于更新数据时所需更新字段及其值或查询条件的封装

其中查询条件的封装与LambdaEsQueryWrapper中提供的方法一致,不一样的只有set方法

set

set(String column,Object val)
set(boolean condition,String column,Object val)

• SQL SET 字段
• 例: set("name", "老李头")
• 例: set("name", "")--->数据库字段值变为空字符串
• 例: set("name", null)--->数据库字段值变为null

使用案例:

    /**
     * LambdaEsUpdateWrapper 使用案例-根据条件更新数据
     */
    @Test
    public void testUpdate() {
        // case1: 根据条件更新和实体对象更新
        LambdaEsUpdateWrapper wrapper = new LambdaEsUpdateWrapper<>();
        wrapper.eq(Document::getTitle, title1);
        Document document = new Document();
        document.setTitle("隔壁老王王");
        document.setContent("推*技术过软");
        document.setCustomField("乌拉巴拉中魔仙");
        documentMapper.update(document, wrapper);

        // case2 另一种省略实体的简单写法,语法与MP一致
        LambdaEsUpdateWrapper wrapper1 = new LambdaEsUpdateWrapper<>();
        wrapper1.eq(Document::getTitle, title1);
        wrapper1.set(Document::getContent,"推*技术过软")
                .set(Document::getCustomField,"乌拉巴拉中魔仙");
        documentMapper.update(null,wrapper1);
    }

二，索引CRUD

1，索引托管模式

前言

ES难用,索引首当其冲,索引的创建和更新不仅复杂,而且难于维护,一旦索引有变动,就必须面对索引重建带来的服务停机和数据丢失等问题... 尽管ES官方提供了索引别名机制来解决问题,但门槛依旧很高,步骤繁琐,在生产环境中由人工操作非常容易出现失误带来严重的问题. 为了解决这些痛点,Easy-Es提供了多种策略,将用户彻底从索引的维护中解放出来,我们提供了多种索引处理策略,来满足不同用户的个性化需求. 通过对索引的初体验,相信您也可以更深体会到EE的成熟度和易用性. 其中全自动平滑模式,首次采用全球领先的"哥哥你不用动,EE我全自动"的模式,索引的创建,更新,数据迁移等所有全生命周期均无需用户介入,由EE全自动完成,过程零停机,连索引类型都可智能自动推断,一条龙服务,包您满意.是全球开源首创,充分借鉴了JVM垃圾回收算法思想,史无前例,尽管网上已有平滑过渡方案,但并非全自动,过程依旧靠人工介入,我为EE代言,请放心将索引托管给EE,索引只有在彻底迁移成功才会删除旧索引,否则均不会对原有索引和数据造成影响,发生任何意外均能保留原索引和数据,所以安全系数很高.

温馨提示: 新手上路可尽量选择手动挡一键模式,老司机(熟悉每种模式的原理及源码)您请随意~ 追求生产环境稳定性,建议您采用手动挡模式,我们手动挡也提供了非常友好的一键创建功能,使用起来也是甜甜的. 自动挡模式,建议您在充分了解其运作原理和源码后再上生产,否则不少小白在没弄明白原理和如何正确配置就无脑上生产,容易被自己坑到,弄明白了请随便,我们的平滑模式实际上也是非常安全的.

自动托管之平滑模式(自动挡-雪地模式) 默认开启此模式

在此模式下,索引的创建更新数据迁移等全生命周期用户均不需要任何操作即可完成,过程零停机,用户无感知,可实现在生产环境的平滑过渡,类似汽车的自动档-雪地模式,平稳舒适,彻底解放用户,尽情享受自动驾驶的乐趣! 需要值得特别注意的是,在自动托管模式下,系统会自动生成一条名为ee-distribute-lock的索引,该索引为框架内部使用,用户可忽略,若不幸因断电等其它因素极小概率下发生死锁,可删除该索引即可.另外,在使用时如碰到索引变更,原索引名称可能会被追加后缀_s0或_s1,不必慌张,这是全自动平滑迁移零停机的必经之路,索引后缀不影响使用,框架会自动激活该新索引.关于_s0和_s1后缀,在此模式下无法避免,因为要保留原索引数据迁移,又不能同时存在两个同名索引,凡是都是要付出代价的，如果您不认可此种处理方式,可继续往下看,总有一种适合您

其核心处理流程梳理如下图所示,不妨结合源码看,更容易理解:

 自动托管之非平滑模式(自动挡-运动模式)

在此模式下,索引额创建及更新由EE全自动异步完成,但不处理数据迁移工作,速度极快类似汽车的自动挡-运动模式,简单粗暴,弹射起步! 适合在开发及测试环境使用,当然如果您使用logstash等其它工具来同步数据,亦可在生产环境开启此模式,在此模式下不会出现_s0和_s1后缀,索引会保持原名称.

提示

以上两种自动模式中,索引信息主要依托于实体类,如果用户未对该实体类进行任何配置,EE依然能够根据字段类型智能推断出该字段在ES中的存储类型,此举可进一步减轻开发者负担,对刚接触ES的小白更是福音.

当然,仅靠框架自动推断是不够的,我们仍然建议您在使用中尽量进行详细的配置,以便框架能自动创建出生产级的索引.举个例子,例如String类型字段,框架无法推断出您实际查询中对该字段是精确查询还是分词查询,所以它无法推断出该字段到底用keyword类型还是text类型,倘若是text类型,用户期望的分词器是什么? 这些都需要用户通过配置告诉框架,否则框架只能按默认值进行创建,届时将不能很好地完成您的期望.

自动推断类型的优先级 < 用户通过注解指定的类型优先级

自动推断映射表:

JAVA	ES
byte	byte
short	short
int	integer
long	long
float	float
double	double
BigDecimal	keyword
char	keyword
String	keyword_text
boolean	boolean
Date	date
LocalDate	date
LocalDateTime	date
List	text

"自动挡"模式下的最佳实践示例:

@Data
@IndexName(shardsNum = 3,replicasNum = 2) // 可指定分片数,副本数,若缺省则默认均为1
public class Document {
    /**
     * es中的唯一id,如果你想自定义es中的id为你提供的id,比如MySQL中的id,请将注解中的type指定为customize,如此id便支持任意数据类型)
     */
    @IndexId(type = IdType.CUSTOMIZE)
    private Long id;
    /**
     * 文档标题,不指定类型默认被创建为keyword_text类型,可进行精确查询
     */
    private String title;
    /**
     * 文档内容,指定了类型及存储/查询分词器
     */
    @HighLight(mappingField="highlightContent")
    @IndexField(fieldType = FieldType.TEXT, analyzer = Analyzer.IK_SMART, searchAnalyzer = Analyzer.IK_MAX_WORD)
    private String content;
    /**
     * 作者 加@TableField注解,并指明strategy = FieldStrategy.NOT_EMPTY 表示更新的时候的策略为 创建者不为空字符串时才更新
     */
    @IndexField(strategy = FieldStrategy.NOT_EMPTY)
    private String creator;
    /**
     * 创建时间
     */
    @IndexField(fieldType = FieldType.DATE, dateFormat = "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis")
    private String gmtCreate;
    /**
     * es中实际不存在的字段,但模型中加了,为了不和es映射,可以在此类型字段上加上 注解@TableField,并指明exist=false
     */
    @IndexField(exist = false)
    private String notExistsField;
    /**
     * 地理位置经纬度坐标 例如: "40.13933715136454,116.63441990026217"
     */
    @IndexField(fieldType = FieldType.GEO_POINT)
    private String location;
    /**
     * 图形(例如圆心,矩形)
     */
    @IndexField(fieldType = FieldType.GEO_SHAPE)
    private String geoLocation;
    /**
     * 自定义字段名称
     */
    @IndexField(value = "wu-la")
    private String customField;

    /**
     * 高亮返回值被映射的字段
     */
    private String highlightContent;
}

手动模式(手动挡)

在此模式下,索引的所有维护工作EE框架均不介入,由用户自行处理,EE提供了开箱即用的索引CRUD相关API,您可以选择使用该API手动维护索引,由于API高度完善,尽管是手动挡,但使用起来依旧简单到爆,一行代码搞定索引创建.当然您亦可通过es-head等工具来维护索引,总之在此模式下,您拥有更高的自由度,比较适合那些质疑EE框架的保守用户或追求极致灵活度的用户使用,类似汽车的手动挡

手动挡模式下,EE提供了如下API,供用户进行便捷调用：

• indexName需要用户手动指定
• 对象 Wrapper 为 条件构造器

    // 获取索引信息
    GetIndexResponse getIndex();
    // 获取指定索引信息
    GetIndexResponse getIndex(String indexName);
    // 是否存在索引
    Boolean existsIndex(String indexName);
    // 根据实体及自定义注解一键创建索引
    Boolean createIndex();
    // 创建索引
    Boolean createIndex(LambdaEsIndexWrapper wrapper);
    // 更新索引
    Boolean updateIndex(LambdaEsIndexWrapper wrapper);
    // 删除指定索引
    Boolean deleteIndex(String indexName);

 上述API,我们仅演示创建索引,其它过于简单,不在这里赘述，如有需要可移步至源码test模块查看. 通过API手动创建索引,我们提供了两种方式

方式一:根据实体类及自定义注解一键创建(推荐),99.9%场景适用

/**
 * 实体类信息
**/
@Data
@IndexName(shardsNum = 3, replicasNum = 2, keepGlobalPrefix = true)
public class Document {
    /**
     * es中的唯一id,如果你想自定义es中的id为你提供的id,比如MySQL中的id,请将注解中的type指定为customize或直接在全局配置文件中指定,如此id便支持任意数据类型)
     */
    @IndexId(type = IdType.CUSTOMIZE)
    private String id;
    /**
     * 文档标题,不指定类型默认被创建为keyword类型,可进行精确查询
     */
    private String title;
    /**
     * 文档内容,指定了类型及存储/查询分词器
     */
    @HighLight(mappingField = "highlightContent")
    @IndexField(fieldType = FieldType.TEXT, analyzer = Analyzer.IK_SMART, searchAnalyzer = Analyzer.IK_MAX_WORD)
    private String content;
    // 省略其它字段...
}

 @Test
    public void testCreateIndexByEntity() {
        // 然后通过该实体类的mapper直接一键创建,非常傻瓜级
        documentMapper.createIndex();
    }

提示

实体类中的注解用法可参考注解章节,整体比较傻瓜级,和MP中的注解用法高度相似.

方式二:通过api创建,每个需要被索引的字段都需要处理,比较繁琐,但灵活性最好,支持所有es能支持的所有索引创建,供0.01%场景使用(不推荐)

    @Test
    public void testCreatIndex() {
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        // 此处简单起见 索引名称须保持和实体类名称一致,字母小写 后面章节会教大家更如何灵活配置和使用索引
        wrapper.indexName(Document.class.getSimpleName().toLowerCase());

        // 此处将文章标题映射为keyword类型(不支持分词),文档内容映射为text类型,可缺省
        // 支持分词查询,内容分词器可指定,查询分词器也可指定,,均可缺省或只指定其中之一,不指定则为ES默认分词器(standard)
        wrapper.mapping(Document::getTitle, FieldType.KEYWORD)
                .mapping(Document::getContent, FieldType.TEXT,Analyzer.IK_MAX_WORD,Analyzer.IK_MAX_WORD);
        
        // 如果上述简单的mapping不能满足你业务需求,可自定义mapping
        // wrapper.mapping(Map);

        // 设置分片及副本信息,3个shards,2个replicas,可缺省
        wrapper.settings(3,2);

        // 如果上述简单的settings不能满足你业务需求,可自定义settings
        // wrapper.settings(Settings);
        
        // 设置别名信息,可缺省
        String aliasName = "daily";
        wrapper.createAlias(aliasName);
        
        // 创建索引
        boolean isOk = documentMapper.createIndex(wrapper);
        Assert.assertTrue(isOk);
    }

温馨提示

实体类中,id字段不需要创建索引,否则会报错.

由于ES索引改动自动重建的特性,因此本接口设计时将创建索引所需的mapping,settings,alias信息三合一了,尽管其中每一项配置都可缺省,但我们仍建议您在创建索引前提前规划好以上信息,可以规避后续修改带来的不必要麻烦,若后续确有修改,您仍可以通过别名迁移的方式(推荐,可平滑过渡),或删除原索引重新创建的方式进行修改

配置启用模式

以上三种模式的配置,您只需要在您项目的配置文件application.properties或application.yml中加入一行配置即可:

easy-es:
  socketTimeout: 600000 # 请求通信超时时间 单位:ms 默认值600000ms 在平滑模式下,由于要迁移数据,用户可根据数据量大小调整此参数值大小,否则请求容易超时导致索引托管失败,建议您尽量给大不给小,跟那玩意一样,大点没事,太小你懂的!
  global-config:
    process_index_mode: smoothly #smoothly:平滑模式, not_smoothly:非平滑模式, manual:手动模式
    async-process-index-blocking: true # 异步处理索引是否阻塞主线程 默认阻塞
    distributed: false # 项目是否分布式环境部署,默认为true, 如果是单机运行可填false,将不加分布式锁,效率更高.
    reindexTimeOutHours: 72 # 重建索引超时时间 单位小时,默认72H 根据迁移索引数据量大小灵活指定

若缺省此行配置,则默认开启平滑模式.

温馨提示

• 自动挡模式下,如果索引托管成功,则会在控制台打印 Congratulations auto process index by Easy-Es is done !
• 自动挡模式下,如果索引托管失败,则会在控制台打印 Unfortunately, auto process index by Easy-Es failed... 以及异常日志,可根据异常日志信息去排查
• 如果索引托管失败,此时用户调用了insert相关API插入数据,由于索引不存在,es(非框架)会自动为用户创建默认索引,创建的索引字段类型为keyword_text类型,并非用户通过注解指定的,因此出现这种情况别问我为啥没生效,因为索引托管因为你的配置或环境原有问题失败了.
• 运行测试模块时强烈建议开启异步处理索引阻塞主线程,否则测试用例跑完后,主线程退出,但异步线程可能还没跑完,可能出现死锁,若不幸出现死锁,删除ee-distribute-lock即可.
• 生产环境或迁移数据量比较大的情况下,可以配置开启非阻塞,这样服务启动更快.
• 以上三种模式,用户可根据实际需求灵活选择,自由体验,在使用过程中如有任何意见或建议可反馈给我们,我们将持续优化和改进,
• EE在索引托管采用了策略+工厂设计模式,未来如果有更多更优模式,可以在不改动原代码的基础上轻松完成拓展,符合开闭原则,也欢迎各路开源爱好者贡献更多模式PR!
• 我们将持续秉承把复杂留给框架,把易用留给用户这一理念,砥砺前行.

2，索引CRUD

提示

EE的索引在前面索引托管章节已有介绍,是支持自动化处理的.但仍有个别场景,用户期望自己来操作索引,也就是前面索引托管章节提到的手动挡模式, 此篇重点介绍手动挡模式下提供的所有API能力,帮助用户快速上手手动挡CRUD索引

前置配置

索引CRUD相关的API都属于手动挡范畴,因此我们执行下述所有API前必须先配置开启手动挡,以免和自动挡冲突.

easy-es:
  global-config:
    process_index_mode: manual # 手动挡模式

创建索引

API介绍

// 1.根据当前mapper对应实体类信息及其注解配置生成索引信息 适用于大多数场景
Boolean createIndex();

// 2.根据当前mapper对应实体类信息及其注解配置生成索引信息 可指定索引名进行创建 适用于定时任务按日期创建索引场景
Boolean createIndex(String indexName);

// 3.根据自定义条件创建索引
Boolean createIndex(Wrapper wrapper);

创建索引一共提供了上述三种方式,使用难度: 方式1 <= 方式2 < 方式3 , 灵活度 方式3 > 方式2 >= 方式1

使用案例:

    /**
     * 方式1
     */
    @Test
    public void testCreateIndexByEntity() {
        // 绝大多数场景推荐使用 简单至上
        documentMapper.createIndex();
    }
    
    /**
     * 方式2
     */
    @Test
    public void testCreateIndexByEntity() {
        // 适用于定时任务按日期创建索引场景
        String indexName = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
        documentMapper.createIndex(indexName);
    }

    /**
     * 方式3
     */
    @Test
    public void testCreateIndex() {
        // 复杂场景使用
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        // 此处简单起见 索引名称须保持和实体类名称一致,字母小写 后面章节会教大家更如何灵活配置和使用索引
        wrapper.indexName(Document.class.getSimpleName().toLowerCase());

        // 此处将文章标题映射为keyword类型(不支持分词),文档内容映射为text类型(支持分词查询)
        wrapper.mapping(Document::getTitle, FieldType.KEYWORD, 2.0f)
                .mapping(Document::getLocation, FieldType.GEO_POINT)
                .mapping(Document::getGeoLocation, FieldType.GEO_SHAPE)
                .mapping(Document::getContent, FieldType.TEXT, Analyzer.IK_SMART, Analyzer.IK_MAX_WORD);

        // 0.9.8+版本,增加对符串字段名称的支持,Document实体中须在对应字段上加上@Tablefield(value="wu-la")用于映射此字段值
        wrapper.mapping("wu-la", FieldType.TEXT, Analyzer.IK_MAX_WORD, Analyzer.IK_MAX_WORD);

        // 设置分片及副本信息,可缺省
        wrapper.settings(3, 2);

        // 设置别名信息,可缺省
        String aliasName = "daily";
        wrapper.createAlias(aliasName);

        // 设置父子信息,若无父子文档关系则无需设置
        wrapper.join("joinField", "document", "comment");

        // 创建索引
        boolean isOk = documentMapper.createIndex(wrapper);
        Assertions.assertTrue(isOk);
    }
    
    /**
     * 方式3 变体,使用难度最高,但灵活性也最高
     */
    @Test
    public void testCreateIndexByMap() {
        // 演示通过自定义map创建索引,最为灵活 可支持es本身能支持的所有索引场景
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        wrapper.indexName(Document.class.getSimpleName().toLowerCase());
        wrapper.settings(3, 2);
        Map map = new HashMap<>();
        Map prop = new HashMap<>();
        Map field = new HashMap<>();
        field.put("type", FieldType.KEYWORD.getType());
        prop.put("this_is_field", field);
        map.put("properties", prop);
        wrapper.mapping(map);
        boolean isOk = documentMapper.createIndex(wrapper);
        Assertions.assertTrue(isOk);
    }

查询索引

API介绍

// 是否存在索引
Boolean existsIndex(String indexName);

// 获取当前mapper对应索引信息
GetIndexResponse getIndex();

// 获取指定索引信息
GetIndexResponse getIndex(String indexName);

使用案例:

    @Test
    public void testExistsIndex() {
        // 测试是否存在指定名称的索引
        String indexName = Document.class.getSimpleName().toLowerCase();
        boolean existsIndex = documentMapper.existsIndex(indexName);
        Assertions.assertTrue(existsIndex);
    }

    @Test
    public void testGetIndex() {
        GetIndexResponse indexResponse = documentMapper.getIndex();
        // 这里打印下索引结构信息 其它分片等信息皆可从indexResponse中取
        indexResponse.getMappings().forEach((k, v) -> System.out.println(v.getSourceAsMap()));
    }

更新索引

API介绍

// 根据条件更新索引
Boolean updateIndex(Wrapper wrapper);

使用案例:

    /**
     * 更新索引
     */
    @Test
    public void testUpdateIndex() {
        // 测试更新索引
        LambdaEsIndexWrapper wrapper = new LambdaEsIndexWrapper<>();
        // 指定要更新哪个索引
        String indexName = Document.class.getSimpleName().toLowerCase();
        wrapper.indexName(indexName);
        wrapper.mapping(Document::getCreator, FieldType.KEYWORD);
        wrapper.mapping(Document::getGmtCreate, FieldType.DATE);
        boolean isOk = documentMapper.updateIndex(wrapper);
        Assertions.assertTrue(isOk);
    }

3，动态索引

尽管我们的每个mapper已经可以决定当前CRUD作用的索引,用户根据不同的mapper就可以操作到不同的索引,这点和MP中不同mapper对应不同的表是一样的. 但是在ES中有一种场景,需要动态索引.例如某公司日志存放在ES中,但日志量极其庞大,并且使用方通常也只关注近三个月内的日志,因此按照年或者月建立索引, 不仅可以提升查询速度和性能,而且可以更好的归类数据.但是EE中的索引是通过@IndexName注解写在代码中的,这就导致用户在想切换索引时还需要重新改代码 并重启项目,这显然不是一个好的解决方案,因此我们额外提供了对动态索引的支持.

• 方式1 直接设置当前mapper对应的索引名 简单粗暴

•     @Test
      public void testActiveIndex(){
          // 设置当前mapper对应的索引 比如原索引名叫document, 设置以后 documentMapper对应的所有CRUD作用的索引将变更为指定的索引名,例如 '2023-03-11'
          String indexName = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
          documentMapper.setCurrentActiveIndex(indexName);
      }
  

提示

此方案虽然简单粗暴又省事,但有两个细节需要注意:

• 不支持分布式环境,因为每个mapper作用的索引是存在jvm缓存中,当前设置操作仅能作用于当前机器,如果要支持分布式环境,则需要用户对每台机器都执行此方法
• 不保证原子性,该操作在执行索引变更时若有其它线程在执行数据的CRUD,并不会阻塞其它线程执行CRUD,因此在高并发场景下,无法保证原子性.

• 方式2 通过wrapper或mapper中具体的方法传入索引名 粒度最细

•     @Test
      public void testSelect() {
          // 支持设置多个查询的索引,用逗号隔开即可
          LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
          wrapper.eq(Document::getTitle, "老汉")
                  .index("你要查询的索引名1","你想查询的索引名2");
          Document document = documentMapper.selectOne(wrapper);
          System.out.println(document);
      }
      
      @Test
      public void testInsert() {
          // 像插入,更新等一些没有wrapper的情况,在mapper中都有提供方法重载,可以直接传入索引名
          Document document = new Document();
          document.setEsId("5");
          document.setTitle("老汉");
          // 支持设置多个查询的索引,用逗号隔开即可
          int successCount = documentMapper.insert(document,"你想插入的索引名1","你想插入的索引名2");
          Assertions.assertEquals(successCount, 1);
      }
  

  落地方案

前面章节我们介绍了手动挡创建索引的API,配合此处提供的索引激活方案就可以轻而易举实现动态索引了

    @Test
    public void testCreateIndexByEntity() {
        // 适用于定时任务按日期创建索引场景
        String indexName = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
        documentMapper.createIndex(indexName);
    }

• 1.写定时任务调用创建索引API创建索引,索引名以你想要的日期格式进行生成并将索引名置入redis缓存

• 2.生成完成后,全局设置当前mapper对应索引名为redis中存入的最新索引名 或者在CRUD时从redis去取最新索引名

当然上面仅是提供一种可行的参考方案,用户还可以根据API提供的能力结合自己项目的特性去设计个性化解决方案.

4，数据同步方案

背景

有不少小伙伴在社区答疑群问我怎么把数据从MySQL同步到ES?想回答好这个问题,需要结合具体的业务场景和数据量以 及具体的开发人数,不同的情况有不同的方案, 就像做菜撒盐一样,我没法直接回答你们,我只能给出一些可行性的方案, 用户可结合自己公司情况,综合考虑

全量同步

顾名思义,就是把现有数据库中的数据全部同步到ES中,通常用是在首次接入ES时,需要初始化全量数据.全量同步可以 考虑 ES官方的Logstash,以及阿里开源的DataX,当然如果你数据量少于千万级别,且数据本身也比较小,想图个简单 省事,使用Easy-Es提供的insertBatch(Collection data)方法批量插入也未尝不可

增量同步

当数据全量同步完成后,用户开始使用ES,此后伴随这数据的CRUD,我们需要把这些数据的变化同步到ES,以确保ES中 的数据实效性,谓之增量同步. 比较成熟的解决方案有阿里开源的Canal,当然你也可以用MQ,甚至本地消息事件(例如 Guava的Event-Bus,springboot自带的Event),根据你的业务数量以及部署机器是否分布式环境等综合考虑选择 适合的方案,上述解决方案原理都类似,基本上都是有MySQL数据变更(增/删/改)时发布消息,然后订阅方订阅到该消 息事件后,将数据变更同步至ES,如此便可以解耦.如果你们并发不算太高,数据量变动也不大的话,用Easy-Es提供的 批量CRUD方法也可以,你可以从MP查出来变更的数据让后调用下方的API完成数据变更,下面API和MP一致,不再介绍.

Integer updateBatchByIds(Collection entityList);
Integer deleteBatchIds(Collection idList);
Integer insertBatch(Collection entityList);
Integer delete(Wrapper wrapper);

提示

在正式同步前,请务必先规划和设计好你的索引结构,分片及副本等索引信息, 由于ES索引发生改变后就得重建索引, 重迁数据,耗时耗力,所以千万不要操之过急,否则你可能一夜回到解放前!

另外上述方案都是一些参考方案,如果你们有找到更好的解决方案也欢迎尝试,而且我这里并不会介绍每种方案具体的 实现,都是成熟的开源组件,大家不会请问度娘或者ChatGPT.

5，数据CRUD

Mapper CRUD 接口

说明

• 通用 CRUD 封装BaseEsMapper (opens new window)接口,为 Easy-Es 启动时自动解析实体对象关系映射转换为 EE 内部对象注入容器
• 泛型 T 为任意实体对象
• insert接口需要区别于MP,具体可看下面insert文档
• 参数 Serializable 为任意类型主键 Easy-Es 不推荐使用复合主键约定每个索引都有自己的唯一 id 主键
• 对象 Wrapper 为 条件构造器
• 针对实体对象T中的 get和set 方法,我们推荐您使用Lombok (opens new window)插件生成,若您采用IDEA自带插件生成,通过Lambda风格获取的字段名称时,会导致部分驼峰命名的字段无法获取正确的字段名. 比如有字段名称叫eName,采用Lombok生成的的get方法为getEName(),但IDEA生成的为geteName(),如此框架底层解析字段名称时就会报错,MP也存在同样问题.

Insert

// 插入一条记录,默认插入至当前mapper对应的索引
Integer insert(T entity);
// 插入一条记录 可指定具体插入的索引,多个用逗号隔开
Integer insert(T entity, String... indexNames);

// 批量插入多条记录
Integer insertBatch(Collection entityList)
// 批量插入多条记录 可指定具体插入的索引,多个用逗号隔开 
Integer insertBatch(Collection entityList, String... indexNames);

特别注意

• 如果您在insert时传入的entity有id并且该id对应数据已存在,则此次insert实际效果为更新该id对应的数据,并且更新不计入insert接口最后返回的成功总条数.
• 当insert接口如上所述,触发了数据更新逻辑,本次更新字段和全局配置的策略（如NOT_NULL/NOT_EMPTY）等均不生效,若您期望策略生效,可以调用update接口而非insert接口.
• 插入后如需id值可直接从entity中取,用法和MP中一致,批量插入亦可直接从原对象中获取插入成功后的数据id,以上接口返回Integer为成功条数.

Delete

 // 根据 ID 删除
Integer deleteById(Serializable id);
// 根据 ID 删除 可指定具体的索引,多个用逗号隔开 
Integer deleteById(Serializable id, String... indexNames);

// 根据 entity 条件，删除记录
Integer delete(LambdaEsQueryWrapper wrapper);

// 删除（根据ID 批量删除）
Integer deleteBatchIds(Collection idList);
// 删除（根据ID 批量删除）可指定具体的索引,多个用逗号隔开 
Integer deleteBatchIds(Collection idList, String... indexNames);

Update

//根据 ID 更新
Integer updateById(T entity);
//根据 ID 更新 可指定具体的索引,多个用逗号隔开 
Integer updateById(T entity, String... indexNames);

// 根据ID 批量更新
Integer updateBatchByIds(Collection entityList);
//根据 ID 批量更新 可指定具体的索引,多个用逗号隔开 
Integer updateBatchByIds(Collection entityList, String... indexNames);

// 根据动态条件 更新记录
Integer update(T entity, LambdaEsUpdateWrapper updateWrapper);

Select

	// 获取总数
    Long selectCount(LambdaEsQueryWrapper wrapper);
    // 获取总数 distinct为是否去重 若为ture则必须在wrapper中指定去重字段
    Long selectCount(Wrapper wrapper, boolean distinct);
    
 	// 根据 ID 查询 
    T selectById(Serializable id);
    // 根据 ID 查询 可指定具体的索引,多个用逗号隔开 
    T selectById(Serializable id, String... indexNames);
	// 查询（根据ID 批量查询）
    List selectBatchIds(Collection idList);
    // 查询（根据ID 批量查询）可指定具体的索引,多个用逗号隔开 
    List selectBatchIds(Collection idList, String... indexNames);
	// 根据动态查询条件，查询一条记录 若存在多条记录 会报错
    T selectOne(LambdaEsQueryWrapper wrapper);
    // 根据动态查询条件，查询全部记录
    List selectList(LambdaEsQueryWrapper wrapper);

提示

• CRUD接口用法基本与MP一致
• 用户需要继承的Mapper为BaseEsMapper，而非BaseMapper
• EE没有提供Service层,而是把MP中一些Service层的方法直接下沉到Mapper层了,用户用起来会更方便

6，四大嵌套查询

背景

MySQL和ES在嵌套查询这块有非常大的差异,所以在2.0版本中特地梳理此章节,帮助各位主公快速了解它们之间的差异并上手

提示

其中MP中已经有的在Easy-Es中用法和功能和它保持一致,降低用户学习及使用成本,只需要学习MP中没有,ES中独有的即可

ES四大嵌套查询

MySQL	Mybatis-Plus	ES	Easy-Es
and 嵌套	and(Consumer)	must	and(Consumer)
or 嵌套	or (Consumer)	should	or (Consumer)
无	无	filter	filter(Consumer)
无	无	must_not	not(Consumer)

ES四大拼接查询

MySQL	Mybatis-Plus	ES	Easy-Es
and 拼接	默认	must	默认
or 拼接	or()	should	or()
无	无	filter	filter()
无	无	must_not	not()

提示

如果您有用过MP,理解上面的差异就比较简单,如果您尚未用过MP也没关系,咱只需要搞清楚嵌套类型与拼接类型的差异即可. 另外关于must和filter的选择,它们在功能上类似,都是表示必须满足的条件,不同之处在于filter不计算得分,性能表现更好,但不支持根据得分排序

嵌套与拼接如何理解和使用

简单来说,嵌套就是有括号的,拼接就是无括号的,或者说嵌套就是里面有东西的,拼接是里面没东西的,怎么理解这段话呢?以大家熟悉的MySQL中的一段SQL为例:

  // 这里面的or就是拼接or
  where name = '老汉' or name = '痴汉';
  // 用MP或EE来写就是
  wrapper.eq(name,"老汉").or().eq(name,"老汉");
  
  
  // 这里面的or是嵌套or
  where name = '老汉' or (age = 18 and size = 18)
  // 用MP或EE来写就是
  wrapper.eq(name,"老汉").or(i->i.eq(age,18).eq(size,18));

通过上面的例子大家应该很好理解拼接和嵌套的差异了,对应到es中,嵌套就是把嵌套中的所有查询条件封装进一个新创建的boolQuery中,然后拼接至根boolQuery,而拼接则是把查询条件直接拼接进根boolQuery中. 在EE中条件与条件直接默认的拼接方式是以and拼接,由于95%的使用场景都是and拼接,所以直接省略了and这种拼接,这点和MP一样

 // sql 
 where name = '老汉' and size = 18
 // 用EE或者MP可以直接写为
 wrapper.eq(name,"老汉").eq(size,18)

如果你需要改写默认的拼接方式只需要加上对应的拼接类型即可,例如:

 // sql
 where name = '老汉' or size = 18
 // 用EE直接写为
 wrapper.eq(name,"老汉").or().eq(size,18);

 // sql
 where name = '老汉' and age != 18
 // 用EE写为
 wrapper.eq(name,"老汉").not().eq(age,18);
  
 // 所有表'非'的条件都可以用not()来拼接
 wrapper.eq(name,"老汉").not().eq(age,18).not().match(desc,'是个纯洁的好男人');

优势对比

相比MySQL只有2中类型嵌套,ES一共有4种,并且在封装方式上差异也非常大,MySQL中的查询条件是以FIFO队列的形式进行封装 但ES中是以树形结构的形式进行封装,在层级比较深的查询中,其难度和复杂程度就算是ES老手也容易搞错,好在有了Easy-Es, 您又可以重回MP时代,大幅减少开发负担和出错的可能,为了保持和MP一样的语法,又要屏蔽ES和MySQL之间巨大的差异,这块 内容我花了近一年的碎片时间才完成,是整个框架中最难啃的一块骨头,不过一切都是值得的,不信咱们接着往下看.

下面我们以一段具体的复杂查询使用案例来对比,优势一目了然:

 // MySQL语法  
 where business_type = 1
 and (state = 9 or (state = 8 and bidding_sign = 1))
 or (business_type = 2 and state in (2,3));

 // Easy-Es及Mybatis-Plus语法 
 wrapper.eq("business_type", 1)
 .and(a -> a.eq("state", 9).or(b -> b.eq("state", 8).eq("bidding_sign", 1)))
 .or(i -> i.eq("business_type", 2).in("state", 2, 3));
        

 // ES原生的RestHighLevel语法
 List values = Arrays.asList(2, 3);
 BoolQueryBuilder boolQueryBuilder = QueryBuilders.boolQuery();
 boolQueryBuilder.must(QueryBuilders.termQuery("business_type", 1));
 boolQueryBuilder.must(QueryBuilders.boolQuery()
                 .must(QueryBuilders.termQuery("state", 9))
                      .should(QueryBuilders.boolQuery().must(QueryBuilders.termQuery("state", 8))
                              .must(QueryBuilders.termQuery("bidding_sign", 1))));
 boolQueryBuilder.should(QueryBuilders.boolQuery().must(QueryBuilders.termQuery("business_type", 2))
               	 .must(QueryBuilders.termsQuery("state", values)));

上面的例子树的最大深度仅为2,如果深度超过2以后ES原生语法就很难看得懂了,更别说正确编码,就算您是ES老手也容易栽坑里,但使用EASY-ES则可以1:1轻松又简单还原复杂SQL

使用示例：

    /**
     * 场景一: 嵌套and的使用 
     */
    @Test
    public void testNestedAnd() {
        // 下面查询条件等价于MySQL中的 select * from document where star_num in (1, 2) and (title = '老汉' or title = '推*')
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.in(Document::getStarNum, 1, 2)
               .and(w -> w.eq(Document::getTitle, "老汉").or().eq(Document::getTitle, "推*"));
        List documents = documentMapper.selectList(wrapper);
    }

    /**
     * 场景二: 拼接and的使用 
     */
    @Test
    public void testAnd(){
        // 下面查询条件等价于MySQL中的 select * from document where title = '老汉' and content like '推*'
        // 拼接and比较特殊,因为使用场景最多,所以条件与条件之间默认就是拼接and,所以可以直接省略,这点和MP是一样的
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
               .match(Document::getContent, "推*");
        List documents = documentMapper.selectList(wrapper);
    }
    
    /**
     * 场景二: 嵌套or的使用 
     */
    @Test
    public void testNestedOr() {
        // 下面查询条件等价于MySQL中的 select * from document where star_num = 1 or (title = '老汉' and creator = '糟老头子')
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getStarNum, 1)
                .or(i -> i.eq(Document::getTitle, "老汉").eq(Document::getCreator, "糟老头子"));
        List documents = documentMapper.selectList(wrapper);
    }

    /**
     * 场景三: 拼接or的使用 
     */
    @Test
    public void testOr() {
        // 下面查询条件等价于MySQL中的 select * from document where title = '老汉' or title = '痴汉'
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
                .or()
                .eq(Document::getTitle, "痴汉");
        List documents = documentMapper.selectList(wrapper);
    }

    /**
     * 场景四: 嵌套filter的使用 其实和场景一一样,只不过filter中的条件不计算得分,无法按得分排序,查询性能稍高
     */
    @Test
    public void testNestedFilter() {
        // 下面查询条件等价于MySQL中的 select * from document where star_num in (1, 2) and (title = '老汉' or title = '推*')
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.in(Document::getStarNum, 1, 2)
                .filter(w -> w.eq(Document::getTitle, "老汉").or().eq(Document::getTitle, "推*"));
        List documents = documentMapper.selectList(wrapper);
    }
    
    /**
     * 场景五: 拼接filter的使用 filter中的条件不计算得分,无法按得分排序,查询性能稍高
     */
    @Test
    public void testFilter() {
        // 下面查询条件等价于MySQL中的 select * from document where title = '老汉'
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.filter().eq(Document::getTitle, "老汉");
        List documents = documentMapper.selectList(wrapper);
    }
    
    /**
     * 场景六: 嵌套mustNot的使用 
     */
    @Test
    public void testNestedNot() {
        // 下面查询条件等价于MySQL中的 select * from document where title = '老汉' and (size != 18 and age != 18)
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
               .not(i->i.eq(size,18).eq(age,18));
        List documents = documentMapper.selectList(wrapper);
    }
    
    /**
     * 场景六: 拼接not()的使用
     */
    @Test
    public void testNot() {
        // 下面查询条件等价于MySQL中的 select * from document where title = '老汉' and  size != 18
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
               .not()
               .eq(size,18);
        List documents = documentMapper.selectList(wrapper);
    }

7，链式调用

链式优势

• 代码整洁,可读性高,易于维护.
• 显著减少代码量,"代码逼格高",隔壁老汉在年度述职时得意地说:那年我双手插兜,略微出手,一行代码就搞定所有!
• 编码爽,对于开发者而言,链式有一个非常明显的优势就是写代码很爽,配合编辑器的友好提示可以快速通过下拉+回车完成编码,这种感觉就像领导都喜欢做选择题而不是填空题!

链式构造

条件构造器及其中的方法本就是支持Lambda+链式调用的,但为了进一步提高链式程度,让隔壁老汉能实现在年会上装13的需求, 我们针对每一种条件构造器都提供了链式构造的方法

// 索引链式构造器
LambdaEsIndexChainWrapper lambdaChainIndex(BaseEsMapper baseEsMapper);
// 查询链式构造器
LambdaEsQueryChainWrapper lambdaChainQuery(BaseEsMapper baseEsMapper);
// 更新(含删除)链式构造器
LambdaEsUpdateChainWrapper lambdaChainUpdate(BaseEsMapper baseEsMapper);

使用案例

    @Test
    public void testOne() {
        // 隔壁老汉写的链式调用
        Document document = EsWrappers.lambdaChainQuery(documentMapper).eq(Document::getTitle, "隔壁老汉").one();
    }    

    @Test
    public void testSelectOne() {
        // 隔壁老王写的半吊子链式调用
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "隔壁老王")
                .limit(1);
        Document document = documentMapper.selectOne(wrapper);
    }

三，扩展功能

1，何为混合查询?

简单理解,就是一半采用EE的语法,一半采用RestHighLevelClient的语法,类似"油电混动",相信你会爱上这种"油电混动"模式,因为它结合了两种模式的优点!

2，为什么要有混合查询?

因为EE目前还没有做到对RestHighLevelClient的功能100%覆盖,目前经过一年多的发展,我们覆盖了RestHighLevelClient约90%左右的API,和99.9%的核心高频使用功能,如此就不可避免的会出现个别场景下,EE不能满足某个特殊需求,此时对EE框架进行二次开发或直接将该需求提给EE作者,在时间上都无法满足开发者需求,有些需求可能产品经理要的比较紧,那么此时,您就可以通过混合查询来解决窘境. 其次,在API设计上其实支持的功能越多越复杂,用户使用起来就越难,这两者是鱼与熊掌,很难兼得,RestHighLevelClient并非有意把API设计的如此难用,他们也非常不容易,复杂的地方光是参数就有上千种排列组合方式,所以我们也无法通过方法重载来简化API使用,即便我们支持了,届时API也会极度臃肿,找一个您想调用的方法更是难上加难,一样会被您无情吐槽,因此我们只简化了99.9%的高频核心API, 其它的低频API,需要您通过混合查询来实现

3，如何使用混合查询?

在我没提供此篇文档时,尽管我提供了混合查询的API和简单介绍,但很多人还不知道有此功能,更不知道该如何使用,所以这里我以一个具体的案例,给大家演示如何使用混合查询,供大家参考,主公们别担心篇幅多,其实非常非常简单,只是我教程写的细.

以上面打车的场景为例,我们来看下用EE怎么查询?上面查询可以分为两部分

• EE支持的常规查询:如周围3公里内,司机性别为女,查询驾龄>=3年...
• EE不支持的非常规查询:按照复杂的排序规则排序(写此篇文档时是不支持的,现已支持,但这不重要,本篇仅以此来演示混合查询的使用)

对于支持的部分,我们可以直接调用EE,由EE先构建一个SearchSourceBuilder出来

// 假设该乘客所在位置经纬度为 31.256224D, 121.462311D
LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
wrapper.geoDistance(Driver::getLocation, 3.0, DistanceUnit.KILOMETERS, new GeoPoint(31.256224D, 121.462311D))
       .eq(Driver::getGender,"女")
       .ge(Driver::getDriverAge,3)
       .eq(Driver::getCarModel,"商务车");
SearchSourceBuilder searchSourceBuilder = driverMapper.getSearchSourceBuilder(wrapper);

对于不支持的语句,可以继续用RestHighLevelClient的语法进行封装,封装好了,直接调用EE提供的混合查询接口,就可以完成整个查询.

// 此处的searchSourceBuilder由上面EE构建而来,我们继续对其追加排序参数
searchSourceBuilder.sort(
        new GeoDistanceSortBuilder("location", 31.256224D, 121.462311D)
                 .order(SortOrder.DESC)
                 .unit(DistanceUnit.KILOMETERS)
                 .geoDistance(GeoDistance.ARC)
);
wrapper.setSearchSourceBuilder(searchSourceBuilder);
List drivers = driverMapper.selectList(wrapper);

4，混合查询的几种正确使用姿势

使用案例：

    /**
     * 正确使用姿势0(最实用,最简单,最推荐的使用姿势)：EE满足的语法,直接用,不满足的可以构造原生QueryBuilder,然后通过wrapper.mix传入QueryBuilder
     * @since 2.0.0-beta2 2.0.0-beta2才正式引入此方案,此方案为混合查询的最优解决方案,由于QueryBuilder涵盖了ES中全部的查询,所以通过此方案
     * 理论上可以处理任何复杂查询,并且可以和EE提供的四大嵌套类型无缝衔接,彻底简化查询,解放生产力!
     */
    @Test
    public void testMix0(){
        // 查询标题为老汉，内容匹配 推*，且最小匹配度不低于80%的数据
        // 当前我们提供的开箱即用match并不支持设置最小匹配度,此时就可以自己去构造一个matchQueryBuilder来实现
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        QueryBuilder queryBuilder = QueryBuilders.matchQuery("content", "推*").minimumShouldMatch("80%");
        wrapper.eq(Document::getTitle,"老汉").mix(queryBuilder);
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
    }

    /**
     * 混合查询正确使用姿势1: EE提供的功能不支持某些过细粒度的功能,所有查询条件通过原生语法构造,仅利用EE提供的数据解析功能
     */
    @Test
    public void testMix1() {
        // RestHighLevelClient原生语法
        SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
        searchSourceBuilder.query(QueryBuilders.matchQuery("content", "推*").minimumShouldMatch("80%"));

        // 仅利用EE查询并解析数据功能
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.setSearchSourceBuilder(searchSourceBuilder);
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
    }


    /**
     * 混合查询正确使用姿势2: 其它都能支持,仅排序器不支持,这种情况可以只按ES原生语法构造所需排序器SortBuilder,其它用EE完成
     */
    @Test
    public void testMix2() {
        // EE满足的语法
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
                .match(Document::getContent, "推*");

        // RestHighLevelClient原生语法
        Script script = new Script("doc['star_num'].value");
        ScriptSortBuilder scriptSortBuilder = SortBuilders.scriptSort(script,ScriptSortBuilder.ScriptSortType.NUMBER).order(SortOrder.DESC);

        // 利用EE查询并解析数据
        wrapper.sort(scriptSortBuilder);
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
    }

    /**
     * 混合查询正确使用姿势3: 其它功能都能支持,但需要向SearchSourceBuilder中追加非query参数
     */
    @Test
    public void testMix3() {
        // EE满足的语法
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
                .match(Document::getContent, "推*");
        SearchSourceBuilder searchSourceBuilder = documentMapper.getSearchSourceBuilder(wrapper);

        // 追加或者设置一些SearchSourceBuilder支持但EE暂不支持的参数 不建议追加query参数,因为如果追加query参数会直接覆盖上面EE已经帮你生成好的query,以最后set的query为准
        searchSourceBuilder.timeout(TimeValue.timeValueSeconds(3L));
        wrapper.setSearchSourceBuilder(searchSourceBuilder);
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
    }


    /**
     * 查询条件中可以利用大多数基本查询,但EE提供的聚合功能不能满足需求的情况下,需要自定义聚合器
     */
    @Test
    public void textMix4() {
        // EE满足的语法
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
                .match(Document::getContent, "推*");
        SearchSourceBuilder searchSourceBuilder = documentMapper.getSearchSourceBuilder(wrapper);

        // RestHighLevelClient原生语法
        AggregationBuilder aggregation = AggregationBuilders.terms("titleAgg")
                .field("title");
        searchSourceBuilder.aggregation(aggregation);
        wrapper.setSearchSourceBuilder(searchSourceBuilder);
        SearchResponse searchResponse = documentMapper.search(wrapper);
        // TODO 聚合后的信息是动态的,框架无法解析,需要用户根据聚合器类型自行从桶中解析,参考RestHighLevelClient官方Aggregation解析文档
    }

5，混合查询错误的使用姿势

EE支持的混合查询使用方案我已经全部列在上面正确的使用姿势中了,已经能涵盖任何一种使用场景了, 请勿凭空捏造凭空想象然后按自己认为没问题的方式来写.

下面就演示两种典型的不支持场景:

    /**
     * 不支持的混合查询1: 追加覆盖问题
     */
    @Test
    public void textNotSupportMix() {
        // EE满足的语法
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
                .match(Document::getContent, "推*");
        SearchSourceBuilder searchSourceBuilder = documentMapper.getSearchSourceBuilder(wrapper);

        // 用户又想在上面的基础上,再追加一些个性化的查询参数进去 但实际上此时执行查询时,查询条件仅仅是最后设置的title=隔壁老王,前面的老汉推*会被覆盖
        searchSourceBuilder.query(QueryBuilders.matchQuery("title", "隔壁老王"));
        wrapper.setSearchSourceBuilder(searchSourceBuilder);
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
        // 思考: 为什么会被覆盖? 因为目前技术上做不到,查询树已经建立好了,es底层并没有提供向树的指定层级上继续追加查询条件的API
    }

    /**
     * 不支持的混合查询2: 脱裤子放P 自欺欺人系列
     */
    @Test
    public void testNotSupportMix2() {
        // EE满足的语法
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.eq(Document::getTitle, "老汉")
                .match(Document::getContent, "推*");

        // SearchSourceBuilder的构造是自己new出来的,不是通过mapper.getSearchSourceBuilder(wrapper)构造 相当于脱裤子放P,那么上面的查询条件老汉推*自然不会生效
        SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
        searchSourceBuilder.minScore(10.5f);
        wrapper.setSearchSourceBuilder(searchSourceBuilder);
        List documents = documentMapper.selectList(wrapper);
        System.out.println(documents);
    }

6，原生查询

API

	// 半原生查询(也可以归于混合查询,通常在自定义聚合Aggregation时使用)
    SearchResponse search(LambdaEsQueryWrapper wrapper) throws IOException;
	
	// 标准原生查询 可指定 RequestOptions
    SearchResponse search(SearchRequest searchRequest, RequestOptions requestOptions) throws IOException;

温馨提示

对于混合查询仍无法解决的场景,您可以调用我们提供的标准原生查询方法进行查询,入参和返回均为RestHighLevelClient原生,和直接使用RestHighLevelClient查询一致 如果您需要在代码中用到RestHighLevelClient,您可以直接使用@Autowired注解注入使用,EE已经帮您自动配置了该bean.

@Service
public class xxxService{
    // 在需要的地方直接注入即可
    @Autowried
    private RestHighLevelClient restHighLevelClient;
}

如果您连EE自动装配的RestHighLevelClient都需要自定义,那我们也是支持的,因为我们在自动装配的类上加了@ConditionalOnClass(RestHighLevelClient.class)注解, 如果您已经自己配置了RestHighLevelClient,那么框架则以您配置的RestHighLevelClient为准,EE为您提供了极致的灵活度和拓展性,确保用得放心.

7，分页查询

关于分页,我们支持了ES的三种分页模式,大家可参考下表,按需选择.

分页方式	性能	优点	缺点	应用场景
from+size 浅分页	低	灵活性好,实现简单	深度分页问题	数据量比较小，能容忍深度分页问题
scroll 滚动查询	中	解决了深度分页问题	无法反应数据的实时性	海量数据的导出需要查询海量结果集的数据
search_after	高	性能最好,不存在深度分页问题，能够反应数据的实时变化	实现复杂，需要有一个全局唯一的字段连续分页的实现会比较复杂，因为每一次查询都需要上次查询的结果，它不适用于大幅度跳页查询	海量数据的分页

浅分页

    // 物理分页
    EsPageInfo pageQuery(LambdaEsQueryWrapper wrapper, Integer pageNum, Integer pageSize);

温馨提示

无需集成任何插件,即可使用分页查询,本查询属于物理分页，基于size+from的浅分页模式,适用于查询数据量少于1万的情况,如您需要 在一些高阶语法的使用场景中,目前已知的有聚合字段的返回,我们分页器尚不能支持,需要您自己封装分页,其它场景基本都能完美支持,用起来无比简单. 注意PageInfo是由本框架提供的,如果你项目中已经有目前最受欢迎的开源分页插件PageHelper,请在引入包的时候注意别引入错误了,EE采用和PageHelper一样的返回字段,您无需担心字段名称不统一带来的额外工作量.

使用示例:

    @Test
    public void testPageQuery() {
        LambdaEsQueryWrapper wrapper = new LambdaEsQueryWrapper<>();
        wrapper.match(Document::getTitle, "老汉");
        EsPageInfo documentPageInfo = documentMapper.pageQuery(wrapper,1,10);
        System.out.println(documentPageInfo);
    }

滚动查询

    // 滚动查询
    SearchResponse scroll(SearchScrollRequest searchScrollRequest, RequestOptions requestOptions) throws IOException;

提示

若您有需要进行超大量的数据查询和分页需求,可以采用滚动查询来实现,关于滚动查询,我们实际上已经提供了getSearchSourceBuilderAPI用于快速构造出SearchSourceBuilder,配合上面提供的滚动查询API,助力您快速实现滚动查询 当然我们更建议您使用下面searchAfter方式分页,不仅API封装得更好,使用更简单,而且具有其它天然优势。

searchAfter

使用示例

    @Test
    public void testSearchAfter() {
        LambdaEsQueryWrapper lambdaEsQueryWrapper = EsWrappers.lambdaQuery(Document.class);
        lambdaEsQueryWrapper.size(10);
        // 必须指定一种排序规则,且排序字段值必须唯一 此处我选择用id进行排序 实际可根据业务场景自由指定,不推荐用创建时间,因为可能会相同
        lambdaEsQueryWrapper.orderByDesc(Document::getId);
        SAPageInfo saPageInfo = documentMapper.searchAfterPage(lambdaEsQueryWrapper, null, 10);
        // 第一页
        System.out.println(saPageInfo);
        Assertions.assertEquals(10, saPageInfo.getList().size());

        // 获取下一页
        List