Easy-Es: An ORM Framework for Elasticsearch in Java

Easy-Es (EE) is an ORM framework built on top of Elasticsearch's RestHighLevelClient, aiming to simplify development and improve efficiency.

If you have used Mybatis-Plus, you can quickly get started with EE, which can be regarded as the Elasticsearch version of MP, incorporating ES‑specific features.

Applicable Scenarios

Search services: document libraries, e‑commerce product search, massive system log retrieval.

Q&A services (essentially search): online intelligent customer service, chatbots.

Map services: ride‑hailing apps, food‑delivery apps, community group‑buying, social networking.

…

Philosophy

Leave simplicity, ease of use, and convenience to the user; hide complexity inside the framework.

Make Elasticsearch easy to use and strive to become the most popular ES development framework worldwide.

Quick Start

If you are familiar with Mybatis-Plus, you can start using Easy-Es without further documentation; it is essentially the Mybatis‑Plus counterpart for Elasticsearch.

Refer to the Spring Boot integration demo at https://www.easy-es.cn/pages/e12389/ for a quick setup.

Dependency

Maven:

<!-- 引入easy-es最新版本的依赖-->
<dependency>
    <groupId>org.dromara.easy-es</groupId>
    <artifactId>easy-es-boot-starter</artifactId>
    <!-- Latest Version is the current version, e.g., 2.0.0 -->
    <version>Latest Version</version>
</dependency>
<!-- Exclude Spring Boot's built‑in ES client to avoid conflicts -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.elasticsearch.client</groupId>
            <artifactId>elasticsearch-rest-high-level-client</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.elasticsearch</groupId>
            <artifactId>elasticsearch</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.14.0</version>
</dependency>
<dependency>
    <groupId>org.elasticsearch</groupId>
    <artifactId>elasticsearch</artifactId>
    <version>7.14.0</version>
</dependency>

Gradle:

compile group: 'org.dromara.easy-es', name: 'easy-es-boot-starter', version: 'Latest Version'

Configuration

Add the required settings to application.yml:

easy-es:
  enable: true   # default true, set false to disable the framework
  address: 127.0.0.1:9200   # ES address, multiple nodes separated by commas
  username: elastic   # optional
  password: WG7WVmuNMtM4GwNYkyWH   # optional

In the Spring Boot main class, add the @EsMapperScan annotation to scan mapper packages:

@SpringBootApplication
@EsMapperScan("com.xpc.easyes.sample.mapper")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Usage Example

Define a Document entity (using Lombok for brevity):

@Data
@IndexName
public class Document {
    /** es unique id */
    private String id;
    /** document title */
    private String title;
    /** document content */
    private String content;
}

Create a mapper interface extending the base ES mapper:

public interface DocumentMapper extends BaseEsMapper<Document> { }

Create the index (manual mode):

@Test
public void testCreateIndex() {
    // framework generates the index from annotations
    boolean success = documentMapper.createIndex();
    Assertions.assertTrue(success);
}

Perform CRUD operations in test methods:

// Insert
@Test
public void testInsert() {
    Document document = new Document();
    document.setTitle("老汉");
    document.setContent("技术过硬");
    int successCount = documentMapper.insert(document);
    System.out.println(successCount);
}

// Select
@Test
public void testSelect() {
    String title = "老汉";
    Document document = EsWrappers.lambdaChainQuery(documentMapper)
        .eq(Document::getTitle, title)
        .one();
    System.out.println(document);
    Assert.assertEquals(title, document.getTitle());
}

// Update
@Test
public void testUpdate() {
    LambdaEsUpdateWrapper<Document> wrapper = new LambdaEsUpdateWrapper<>();
    wrapper.eq(Document::getTitle, title1);
    Document document2 = new Document();
    document2.setTitle("隔壁老李");
    document2.setContent("技术过软");
    documentMapper.update(document2, wrapper);
}

// Delete
@Test
public void testDelete() {
    LambdaEsQueryWrapper<Document> wrapper = new LambdaEsQueryWrapper<>();
    String title = "隔壁老李";
    wrapper.eq(Document::getTitle, title);
    int successCount = documentMapper.delete(wrapper);
    System.out.println(successCount);
}

Related Links

Project address: https://gitee.com/dromara/easy-es

Official site: https://www.easy-es.cn/