easy-query

https://github.com/xuejmnet/easy-query-doc
Admin
A powerful and elegant ORM for Java/Kotlin with zero dependencies, providing implicit queries,...
Tokens:977,071
Snippets:5,358
Trust Score:8.9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Full example: entity, client setup, and SQL output for keyword handling

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/framework/key-word.md

Complete example showing an entity with a 'key' column (a database keyword), client setup, table creation, insert, and query. The SQL output shows backticks around 'key' and 'test_table' for MySQL. The example uses assertions to verify results.

```java
@Table("test_table")
@Data
@EntityProxy
@ToString
public class EntityColumnKey implements ProxyEntityAvailable<EntityColumnKey , EntityColumnKeyProxy> {
    @Column(primaryKey = true)
    private String id;
    private String key;
}
```

```java
EasyQueryClient client = EasyQueryBootstrapper.defaultBuilderConfiguration()
        .setDefaultDataSource(dataSource)
        .optionConfigure(op -> {
            //Perform a series of optional configurations
            //op.setPrintSql(true);
        })
        //Set the correct database
        .useDatabaseConfigure(new MySQLDatabaseConfiguration())
        .build();
EasyEntityQuery easyEntityQuery = new DefaultEasyEntityQuery(easyQueryClient);

DatabaseCodeFirst databaseCodeFirst = easyEntityQuery.getDatabaseCodeFirst();
databaseCodeFirst.createDatabaseIfNotExists();
CodeFirstCommand codeFirstCommand = databaseCodeFirst.syncTableCommand(Arrays.asList(EntityColumnKey.class));
codeFirstCommand.executeWithTransaction(arg->arg.commit());
EntityColumnKey entityColumnKey = new EntityColumnKey();
entityColumnKey.setId("123");
entityColumnKey.setKey("456");
long l = easyEntityQuery.insertable(entityColumnKey).executeRows();
Assert.assertEquals(1, l);
EntityColumnKey entityColumnKey1 = easyEntityQuery.queryable(EntityColumnKey.class)
        .where(o -> o.key().eq("456")).firstOrNull();
Assert.assertNotNull(entityColumnKey1);
```

```sql
==> Preparing: CREATE TABLE IF NOT EXISTS `test_table` (`id` VARCHAR(32) NOT NULL,`key` VARCHAR(32) NULL,PRIMARY KEY (`id`))
<== Total: 0
==> Preparing: INSERT INTO `test_table` (`id`,`key`) VALUES (?,?) 
==> Parameters: 123(String),456(String)
<== Total: 1
==> Preparing: SELECT `id`,`key` FROM `test_table` WHERE `key` = ? LIMIT 1
==> Parameters: 456(String)
<== Time Elapsed: 3(ms)
<== Total: 1
```

--------------------------------

### Solon controller with GET endpoint

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/guide/solon.md

A simple Solon controller with a GET mapping that returns 'Hello World'.

```java
@Controller
@Mapping("/test")
public class TestController {
    @Mapping(value = "/hello",method = MethodType.GET)
    public String hello(){
        return "Hello World";
    }
}
```

--------------------------------

### JSON: Example response with commentList

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/startup/step2.md

Example JSON response returned by the endpoint. It shows a post object with fields including id, title, content, userId, publishAt, userName, and a commentList array containing up to 3 comments.

```json

    {
        "id": "0c7fd05f-f999-4fcc-8c98-c0509b22b7f1",
        "title": "健身计划分享",
        "content": "# 这是用户用户D的帖子内容\n包含丰富的文本内容...",
        "userId": "c529b9ba-a90d-490e-9bad-15ef7c4f33cc",
        "publishAt": "2025-08-03T21:24:00.577",
        "userName": "c529b9ba-a90d-490e-9bad-15ef7c4f33cc",
        "commentList": [
            {
                "id": "67c9ceb0-3eef-44ba-8bbc-c0d1f15f00ad",
                "parentId": "0",
                "content": "期待更多这样的内容",
                "createAt": "2025-08-05T17:24:00.579"
            },
            {
                "id": "d7753586-4bb9-448b-bedb-b178df897bca",
                "parentId": "fa80aaa0-9742-4a02-9209-a08d1bd979df",
                "content": "@用户B 我也这么认为",
                "createAt": "2025-08-06T00:24:00.579"
            },
            {
                "id": "2b40e873-5c0d-41c4-bf10-a38461017300",
                "parentId": "67c9ceb0-3eef-44ba-8bbc-c0d1f15f00ad",
                "content": "@用户C 具体是指哪方面？",
                "createAt": "2025-08-06T03:24:00.579"
            }
        ]
    }

```

--------------------------------

### max and min usage example

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/func/general.md

Shows max() and max().filter() to get the maximum score, with filter applying a condition. The filter uses implicit case when.

```java

    easyEntityQuery.queryable(BlogEntity.class)
            .where(t_blog -> {
                t_blog.content().like("abc");
            }).select(t_blog -> Select.DRAFT.of(
                    t_blog.score().max(),//max(id)
                    t_blog.score().max().filter(() -> {//get max score for titles that are not "scary"
                        t_blog.title().ne("恐怖");
                    })
            )).toList();
```

--------------------------------

### Bootstrap EasyQuery with sharding configuration and register route

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/super/sharding-time.md

Configure EasyQueryClient with sharding options, apply the TopicShardingTimeShardingInitializer, and add the TopicShardingTimeTableRoute. Enable the time job so future tables are pre-created.

```java
EasyQueryClient easyQueryClient = EasyQueryBootstrapper.defaultBuilderConfiguration()
        .setDefaultDataSource(dataSource)
        .optionConfigure(op -> {
            op.setDeleteThrowError(false);
            op.setExecutorCorePoolSize(1);
            op.setExecutorMaximumPoolSize(0);
            op.setMaxShardingQueryLimit(10);
            op.setThrowIfRouteNotMatch(false);
            op.setMaxShardingRouteCount(512);
            op.setDefaultDataSourceMergePoolSize(20);
            //Enable scheduled task, otherwise tomorrow's table or next month's table will not exist in memory
            op.setStartTimeJob(true);
            op.setReverseOffsetThreshold(10);
        })
        .useDatabaseConfigure(new MySQLDatabaseConfiguration())
        .build();
DefaultEasyEntityQuery easyEntityQuery = new DefaultEasyEntityQuery(easyQueryClient);
QueryRuntimeContext runtimeContext = easyQuery.getRuntimeContext();
QueryConfiguration configuration = runtimeContext.getQueryConfiguration();
configuration.applyShardingInitializer(new TopicShardingTimeShardingInitializer());
TableRouteManager tableRouteManager = runtimeContext.getTableRouteManager();
tableRouteManager.addRoute(new TopicShardingTimeTableRoute());
```

--------------------------------

### Create product table

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/ability/delete.md

SQL DDL for the product table used in the example. Includes id, name, deleted_time, and deleted_user_id columns.

```sql
-- Drop product table
DROP TABLE IF EXISTS product CASCADE;

-- Create product table
CREATE TABLE product (
    id INTEGER AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255),
    deleted_time DATETIME,
    deleted_user_id INTEGER
);
```

--------------------------------

### dayOfYear: Get day of year from date

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/func/datetime.md

Returns the day of the year (1-366) for the date. The example queries BlogEntity and asserts that the returned dayOfYear matches the Java LocalDateTime.getDayOfYear().

```java
List<Draft2<LocalDateTime, Integer>> list = easyEntityQuery.queryable(BlogEntity.class)
        .select(t_blog -> Select.DRAFT.of(
                t_blog.createTime(),
                t_blog.createTime().dayOfYear()
        )).toList();
Assert.assertFalse(list.isEmpty());
for (Draft2<LocalDateTime, Integer> item : list) {
    int dayOfYear = item.getValue1().getDayOfYear();
    Assert.assertEquals(item.getValue2().intValue(), dayOfYear);
}
```

--------------------------------

### Create two users with addresses (Java)

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/savable/ownership.md

Creates two SaveUser objects with associated SaveUserExt and SaveUserAddress, then saves them using easyEntityQuery.savable().executeCommand(). This is the setup for the ownership change example.

```java

    @PostMapping("/create2")
    @Transactional(rollbackFor = Exception.class)
    @EasyQueryTrack
    public Object create2() {
        ArrayList<SaveUser> users = new ArrayList<>();
        {

            SaveUser saveUser = new SaveUser();
            users.add(saveUser);
            saveUser.setId("XiaoMing1's id");
            saveUser.setName("XiaoMing1");
            saveUser.setAge(19);
            saveUser.setCreateTime(LocalDateTime.now());

            SaveUserExt saveUserExt = new SaveUserExt();
            saveUserExt.setMoney(BigDecimal.ZERO);
            saveUserExt.setHealthy(true);
            saveUser.setSaveUserExt(saveUserExt);

            SaveUserAddress saveUserAddress = new SaveUserAddress();
            saveUserAddress.setId("XiaoMing1's home id");
            saveUserAddress.setProvince("Zhejiang Province");
            saveUserAddress.setCity("Shaoxing City");
            saveUserAddress.setArea("Yuecheng District");
            saveUserAddress.setAddress("XiaoMing1's home");
            saveUser.setSaveUserAddress(saveUserAddress);
        }
        {

            SaveUser saveUser = new SaveUser();
            users.add(saveUser);
            saveUser.setId("XiaoMing2's id");
            saveUser.setName("XiaoMing2");
            saveUser.setAge(19);
            saveUser.setCreateTime(LocalDateTime.now());

            SaveUserExt saveUserExt = new SaveUserExt();
            saveUserExt.setMoney(BigDecimal.ZERO);
            saveUserExt.setHealthy(true);
            saveUser.setSaveUserExt(saveUserExt);

            SaveUserAddress saveUserAddress = new SaveUserAddress();
            saveUserAddress.setId("XiaoMing2's home id");
            saveUserAddress.setProvince("Zhejiang Province");
            saveUserAddress.setCity("Shaoxing City");
            saveUserAddress.setArea("Yuecheng District");
            saveUserAddress.setAddress("XiaoMing2's home");
            saveUser.setSaveUserAddress(saveUserAddress);
        }
        easyEntityQuery.savable(users).executeCommand();
        return "ok";
    }

```

--------------------------------

### Solon 启动类 (Main.java)

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/guide/solon.md

启动 Solon 应用，加载 application.yml 配置文件，访问 http://localhost:8080/test/hello 返回 Hello World。

```java
public class Main {
    public static void main(String[] args) {
        Solon.start(Main.class,args,(app)->{
            app.cfg().loadAdd("application.yml");
        });
    }
}

//输入url http://localhost:8080/test/hello

//返回Hello World
```

--------------------------------

### dayOfWeekSunDayIsLastDay: Get day of week (Sunday=7)

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/func/datetime.md

Returns the day of the week with Monday as 1 through Sunday as 7. The example queries BlogEntity and asserts the value matches Java's DayOfWeek.getValue().

```java

List<Draft2<LocalDateTime, Integer>> list = easyEntityQuery.queryable(BlogEntity.class)
        .select(t_blog -> Select.DRAFT.of(
                t_blog.createTime(),
                t_blog.createTime().dayOfWeekSunDayIsLastDay()
        )).toList();
Assert.assertFalse(list.isEmpty());
for (Draft2<LocalDateTime, Integer> item : list) {
    DayOfWeek dayOfWeek = item.getValue1().getDayOfWeek();
    Assert.assertEquals(item.getValue2().intValue(), dayOfWeek.getValue());
}
```

--------------------------------

### Database script for easy-trans demo

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/framework/easy-trans.md

Creates the database and tables for the easy-trans demo, including the help_code dictionary table and sys_user table, with sample data. Run this script before using the Java entities.

```sql
CREATE DATABASE IF NOT EXISTS easy_trans_demo CHARACTER SET 'utf8mb4';
USE easy_trans_demo;
create table help_code
(
    code varchar(32) not null comment 'code'primary key,
    type int not null comment 'type',
    name varchar(50) not null comment 'Chinese value'
)comment 'dictionary table';

insert into help_code values('1',1,'Male');
insert into help_code values('2',1,'Female');
insert into help_code values('3',2,'Administrator');
insert into help_code values('4',2,'Normal User');


create table sys_user
(
    id varchar(32) not null comment 'id'primary key,
    name varchar(50) not null comment 'name',
    sex varchar(50) not null comment 'gender',
    type varchar(50) not null comment 'user type'
)comment 'user table';
insert into sys_user values('1','XiaoMing','2','3');
insert into sys_user values('2','XiaoGang','1','4');
```

--------------------------------

### Configure MySQL database in console (EasyQueryClient)

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/framework/key-word.md

Shows how to build an EasyQueryClient with the MySQL database configuration. The optionConfigure block allows optional settings like printSql. This is required for correct keyword handling.

```java
EasyQueryClient client = EasyQueryBootstrapper.defaultBuilderConfiguration()
        .setDefaultDataSource(dataSource)
        .optionConfigure(op -> {
            //Perform a series of optional configurations
            //op.setPrintSql(true);
        })
        //Set the correct database
        .useDatabaseConfigure(new MySQLDatabaseConfiguration())
        .build();
```

--------------------------------

### SpringBoot Startup Error Log

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/question.md

Example error log when SpringBoot fails to start due to AOP-related issues. The stack trace shows a java.lang.IllegalStateException: Unable to load cache item from spring-core.

```log
java.lang.IllegalStateException: Unable to load cache item
	at org.springframework.cglib.core.internal.LoadingCache.createEntry(LoadingCache.java:79) ~[spring-core-5.3.29.jar:5.3.29]
	at org.springframework.cglib.core.internal.LoadingCache.get(LoadingCache.java:34) ~[spring-core-5.3.29.jar:5.3.29]
	at org.springframework.cglib.core.AbstractClassGenerator$ClassLoaderData.get(AbstractClassGenerator.java:134) ~[spring-core-5.3.29.jar:5.3.29]
	at org.springframework.cglib.core.AbstractClassGenerator.create(AbstractClassGenerator.java:319) ~[spring-core-5.3.29.jar:5.3.29]
	at org.springframework.cglib.proxy.Enhancer.createHelper(Enhancer.java:572) ~[spring-core-5.3.29.jar:5.3.29]
	at org.springframework.cglib.proxy.Enhancer.createClass(Enhancer.java:419) ~[spring-core-5.3.29.jar:5.3.29]
```

--------------------------------

### dayOfWeek: Get day of week (Sunday=0)

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/func/datetime.md

Returns the day of the week with Sunday as 0, Monday as 1, up to Saturday as 6. The example queries BlogEntity and asserts the value matches Java's DayOfWeek, adjusting for Sunday (0 maps to 7).

```java

List<Draft2<LocalDateTime, Integer>> list = easyEntityQuery.queryable(BlogEntity.class)
        .select(t_blog -> Select.DRAFT.of(
                t_blog.createTime(),
                t_blog.createTime().dayOfWeek()
        )).toList();
Assert.assertFalse(list.isEmpty());
for (Draft2<LocalDateTime, Integer> item : list) {
    DayOfWeek dayOfWeek = item.getValue1().getDayOfWeek();
    int i = item.getValue2().intValue();
    if(i==0){
        Assert.assertEquals(7, dayOfWeek.getValue());
    }else{
        Assert.assertEquals(i, dayOfWeek.getValue());
    }
}
```

--------------------------------

### Instantiate EasyEntityQuery

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/startup/quick-start.md

Code snippet showing how to initialize the EasyEntityQuery object and set up the database schema.

```APIDOC
## [Java] Instantiate EasyEntityQuery

### Description
Initializes the `EasyEntityQuery` object in a simple console environment, sets up the data source, and performs database/table synchronization.

### Method
Java code snippet

### Endpoint
N/A

### Parameters
#### DataSource Configuration
- **jdbcUrl** (String) - Required - JDBC URL for the MySQL database
- **username** (String) - Required - Database username
- **password** (String) - Required - Database password
- **driverClassName** (String) - Required - JDBC driver class name
- **maximumPoolSize** (int) - Required - Maximum connection pool size

### Request Example
```java
HikariDataSource dataSource = new HikariDataSource();
dataSource.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/eq_db?serverTimezone=GMT%2B8&characterEncoding=utf-8&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true");
dataSource.setUsername("root");
dataSource.setPassword("root");
dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
dataSource.setMaximumPoolSize(20);
```

### Response
#### Success Response
- **entityQuery** (EasyEntityQuery) - The initialized query object
- **databaseCodeFirst** (DatabaseCodeFirst) - Used for database/table synchronization

#### Response Example
```java
EasyQueryClient client = EasyQueryBootstrapper.defaultBuilderConfiguration()
        .setDefaultDataSource(dataSource)
        .optionConfigure(op -> {
            //Perform a series of optional configurations
            //op.setPrintSql(true);
        })
        .useDatabaseConfigure(new MySQLDatabaseConfiguration())
        .build();
entityQuery = new DefaultEasyEntityQuery(client);
```
```

--------------------------------

### 自定义AbstractProcessor实现

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/practice/apt/compile-repo.md

创建一个APT处理器类，继承AbstractProcessor。在init中获取Filer、Elements、Types工具，通过getSupportedAnnotationTypes和getSupportedSourceVersion控制处理范围，在process中编写业务逻辑。

```java
//支持的注解全路径 使用方法来实现这两个保证在高版本上的java中不会出现警告
// @SupportedAnnotationTypes({"com.eq.apt.repo.processor.annotations.ProxyRepository"})
// @SupportedSourceVersion(SourceVersion.RELEASE_8)
public class ProxyRepositoryProcessor extends AbstractProcessor {
    private Filer filer;
    private Elements elementUtils;
    private Types typeUtils;
    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
        this.filer = processingEnv.getFiler();
        this.elementUtils = processingEnv.getElementUtils();
        this.typeUtils = processingEnv.getTypeUtils();
    }
    @Override
    public Set<String> getSupportedAnnotationTypes() {
        Set<String> supportedAnnotationTypes = new HashSet<>();
        supportedAnnotationTypes.add(ProxyRepository.class.getCanonicalName());
        return supportedAnnotationTypes;
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        if (!roundEnv.processingOver()) {
            // todo:处理一些业务....
        }
        return false;
    }

}
```

--------------------------------

### Java: Using offset with prev/next in easy-query

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/func/offset.md

Shows how to use the offset function in easy-query to get previous (prev) and next (next) rows, with optional partitionBy, orderBy, default values, and nullOrDefault. The example uses a LocalDateTime default value and demonstrates various offset configurations.

```java
        LocalDateTime time = LocalDateTime.of(2025, 1, 1, 0, 0););

        List<Draft7<String, String, LocalDateTime, LocalDateTime, LocalDateTime, LocalDateTime, LocalDateTime>> list = easyEntityQuery.queryable(SysBankCard.class)
                .select(bank_card -> Select.DRAFT.of(
                        bank_card.type(),
                        bank_card.type().offset(o -> {
                            o.orderBy(bank_card.type()).orderByDescending(bank_card.code());
                        }).prev(1),
                        bank_card.openTime().offset(o -> {
                            o.orderBy(bank_card.type()).orderByDescending(bank_card.code());
                        }).next(1),
                        bank_card.openTime().offset(o -> {
                            o.partitionBy(bank_card.bankId());
                            o.orderBy(bank_card.type()).orderByDescending(bank_card.code());
                        }).next(1),
                        bank_card.openTime().offset(o -> {
                            o.partitionBy(bank_card.bankId());
                            o.orderBy(bank_card.type()).orderByDescending(bank_card.code());
                        }).next(1, time),
                        bank_card.openTime().offset(o -> {
                            o.partitionBy(bank_card.bankId());
                            o.orderBy(bank_card.type()).orderByDescending(bank_card.code());
                        }).next(1).nullOrDefault(time),
                        bank_card.openTime().offset(o -> {
                            o.partitionBy(bank_card.bankId());
                            o.orderBy(bank_card.type()).orderByDescending(bank_card.code());
                        }).next(1, bank_card.openTime()).nullOrDefault(time)
                )).toList();
```

--------------------------------

### Use custom MyPager to get PageResult

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/ability/select/page.md

Shows how to use the custom MyPager in business code to obtain a PageResult. The example queries TopicGenericKey by id "1" with page index 1 and size 2, then asserts the total count and first item's id.

```java
//业务代码返回自定义PageResult<TEntity>
PageResult<TopicGenericKey> pageResult = easyQuery
        .queryable(TopicGenericKey.class)
        .whereById("1")
        .toPageResult(new MyPager<>(1, 2));
Assert.assertEquals(1,pageResult.getTotalCount());
Assert.assertEquals("1",pageResult.getList().get(0).getId());

```

--------------------------------

### 无依赖配置：拷贝三个源码文件

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/guide/spring-boot.md

无依赖配置：从springboot-starter拷贝的三个源码文件，用于支持Spring事务。包含SpringConnectionManager、SpringDataSourceUnit和SpringDataSourceUnitFactory。

```java
public class SpringConnectionManager extends DefaultConnectionManager {

    public SpringConnectionManager(EasyQueryDataSource easyDataSource, EasyConnectionFactory easyConnectionFactory, EasyDataSourceConnectionFactory easyDataSourceConnectionFactory) {
        super(easyDataSource, easyConnectionFactory, easyDataSourceConnectionFactory);
    }

    @Override
    public boolean currentThreadInTransaction() {
        return TransactionSynchronizationManager.isActualTransactionActive() || isOpenTransaction();
    }

    @Override
    public void closeEasyConnection(EasyConnection easyConnection) {
        if(easyConnection==null){
            return;
        }
        //当前没开事务,但是easy query手动开启了
        if (!TransactionSynchronizationManager.isActualTransactionActive()) {
            if (super.isOpenTransaction()) {
                return;
            }
        } else {
            if (super.isOpenTransaction()) {
                throw new EasyQueryException("repeat transaction can't closed connection");
            }
        }
        DataSourceWrapper dataSourceUnit = easyDataSource.getDataSourceNotNull(easyConnection.getDataSourceName(), ConnectionStrategyEnum.ShareConnection);
        DataSourceUtils.releaseConnection(easyConnection.getConnection(), dataSourceUnit.getDataSourceUnit().getDataSource());
    }
}


public class SpringDataSourceUnit extends DefaultDataSourceUnit {
    public SpringDataSourceUnit(String dataSourceName, DataSource dataSource, int mergePoolSize, boolean warningBusy) {
        super(dataSourceName,dataSource,mergePoolSize,warningBusy);
    }

    @Override
    protected Connection getConnection() throws SQLException {
        return DataSourceUtils.getConnection(dataSource);
    }
}


public class SpringDataSourceUnitFactory implements DataSourceUnitFactory {
    private final EasyQueryOption easyQueryOption;

    public SpringDataSourceUnitFactory(EasyQueryOption easyQueryOption){

        this.easyQueryOption = easyQueryOption;
    }
    @Override
    public DataSourceUnit createDataSourceUnit(String dataSourceName, DataSource dataSource, int mergePoolSize) {
        return new SpringDataSourceUnit(dataSourceName,dataSource,mergePoolSize,easyQueryOption.isWarningBusy());
    }
}
```

--------------------------------

### Get time duration with duration() and convert units

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/func/datetime.md

Calculates the duration between a stored createTime and a fixed LocalDateTime (time2025) using the duration() function, converting to days, hours, minutes, seconds, and a specific DateTimeDurationEnum. The default before.duration(after) returns a positive number; reversing the order yields a negative, and abs() can be used for a positive result. The example asserts the computed values against Duration.between() results.

```java
LocalDateTime time2025 = LocalDateTime.of(2025, 1, 1, 0, 0, 0);
List<Draft6<LocalDateTime, Long, Long, Long, Long, Long>> list = easyEntityQuery.queryable(BlogEntity.class)
        .select(t_blog -> Select.DRAFT.of(
                t_blog.createTime(),
                t_blog.createTime().duration(time2025).toDays(),
                t_blog.createTime().duration(time2025).toHours(),
                t_blog.createTime().duration(time2025).toMinutes(),
                t_blog.createTime().duration(time2025).toSeconds(),
                t_blog.createTime().duration(time2025).toValues(DateTimeDurationEnum.Days)
        )).toList();
Assert.assertFalse(list.isEmpty());
for (Draft6<LocalDateTime, Long, Long, Long, Long, Long> item : list) {
    LocalDateTime value1 = item.getValue1();
    Duration between = Duration.between(value1, time2025);

    Assert.assertEquals(between.toDays(), item.getValue2().longValue());
    Assert.assertEquals(between.toHours(), item.getValue3().longValue());
    Assert.assertEquals(between.toMinutes(), item.getValue4().longValue());
    Assert.assertEquals(between.getSeconds(), item.getValue5().longValue());
    Assert.assertEquals(between.toDays(), item.getValue6().longValue());
}
```

--------------------------------

### spring-boot 配置 easy-query 选项

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/framework/config-option.md

配置文件（如application.yml）中配置easy-query选项，包括启用、命名转换、数据库类型、删除行为、SQL打印和映射策略。

```yml
easy-query:
  enable: true
  name-conversion: underlined
  database: mysql
  #如果执行物理删除delete语句将会报错 如果改为false,后续可以通过allowDeleteStatment来允许
  delete-throw: true
  #打印sql显示(需要框架默认有日志以 log.info打印)
  print-sql: true
  #entity映射到dto/vo使用属性匹配模式
  #支持 property_only column_only column_and_property property_first
  mapping-strategy: property_first
  ......
```

--------------------------------

### Single Table Query with Filtering, Grouping, Having, Select, OrderBy, and Limit

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/ability/select/single.md

Complete single table query example using easyEntityQuery. It filters by content, groups by title, applies a having condition on the sum of star, selects a draft with key1, sum, and max, orders by value3 descending, and limits to 2 rows starting at offset 2. The SQL shows the generated embedded view (t1) and the final ordering and limit.

```java
List<Draft3<String, Integer, LocalDateTime>> myBlog = easyEntityQuery.queryable(BlogEntity.class)
        .where(b -> {
            b.content().like("my blog");
        })
        .groupBy(b -> GroupKeys.of(b.title()))
        .having(group -> {
            group.groupTable().star().sum().lt(10);
        })
        //select will wrap select and previous expression as an embedded view (t1 table). If no subsequent chain configuration, will expand; otherwise represented as embedded view (t1 table)
        .select(group -> Select.DRAFT.of(
                group.key1(),//value1
                group.groupTable().star().sum().asAnyType(Integer.class),//value2
                group.groupTable().createTime().max()//value3
        ))
        //If orderBy is not added, embedded view (t1 table) SQL will not be generated
        //Because orderBy is for ordering the previous select result
        .orderBy(group -> group.value3().desc())
        .limit(2,2)//Limit the returned result
        .toList();
```

```sql
-- SQL 1
SELECT
    t1.`value1` AS `value1`,
    t1.`value2` AS `value2`,
    t1.`value3` AS `value3` 
FROM
    (SELECT
        t.`title` AS `value1`,
        SUM(t.`star`) AS `value2`,
        MAX(t.`create_time`) AS `value3` 
    FROM
        `t_blog` t 
    WHERE
        t.`deleted` = false 
        AND t.`content` LIKE '%my blog%' 
    GROUP BY
        t.`title` 
    HAVING
        SUM(t.`star`) < 10) t1 
ORDER BY
    t1.`value3` DESC LIMIT 2,2
```

--------------------------------

### Initialize Easy Query and sync database tables

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/code-first/quick-start.md

Main class that initializes Easy Query with a MySQL HikariCP data source, creates the database if it does not exist, and synchronizes the Company and SysUser tables. Uses MySQLDatabaseConfiguration and executes the sync command within a transaction, printing the SQL.

```java
package com.easy.query.console;

import com.easy.query.api.proxy.client.DefaultEasyEntityQuery;
import com.easy.query.api.proxy.client.EasyEntityQuery;
import com.easy.query.console.entity.Company;
import com.easy.query.console.entity.SysUser;
import com.easy.query.console.vo.CompanyNameAndUserNameVO;
import com.easy.query.console.vo.proxy.CompanyNameAndUserNameVOProxy;
import com.easy.query.core.api.client.EasyQueryClient;
import com.easy.query.core.api.pagination.EasyPageResult;
import com.easy.query.core.basic.api.database.CodeFirstCommand;
import com.easy.query.core.basic.api.database.DatabaseCodeFirst;
import com.easy.query.core.bootstrapper.EasyQueryBootstrapper;
import com.easy.query.core.logging.LogFactory;
import com.easy.query.core.proxy.core.draft.Draft2;
import com.easy.query.core.proxy.sql.Select;
import com.easy.query.mysql.config.MySQLDatabaseConfiguration;
import com.zaxxer.hikari.HikariDataSource;

import javax.sql.DataSource;
import java.util.Arrays;
import java.util.List;

public class Main {
    private static EasyEntityQuery entityQuery;

    public static void main(String[] args) {
        LogFactory.useStdOutLogging();
        DataSource dataSource = getDataSource();
        EasyQueryClient client = EasyQueryBootstrapper.defaultBuilderConfiguration()
                .setDefaultDataSource(dataSource)
                .optionConfigure(op -> {
                    //进行一系列可以选择的配置
                    //op.setPrintSql(true);
                })
                .useDatabaseConfigure(new MySQLDatabaseConfiguration())
                .build();
        entityQuery = new DefaultEasyEntityQuery(client);

        DatabaseCodeFirst databaseCodeFirst = entityQuery.getDatabaseCodeFirst();
        //如果不存在数据库则创建
        databaseCodeFirst.createDatabaseIfNotExists();
        //自动同步数据库表
        CodeFirstCommand command = databaseCodeFirst.syncTableCommand(Arrays.asList(Company.class, SysUser.class));
        //执行命令
        command.executeWithTransaction(arg -> {
            System.out.println(arg.sql);
            arg.commit();
        });
    }

    /**
     * 初始化数据源
     *
     * @return
     */
    private static DataSource getDataSource() {
        HikariDataSource dataSource = new HikariDataSource();
        dataSource.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/eq_db?serverTimezone=GMT%2B8&characterEncoding=utf-8&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true");
        dataSource.setUsername("root");
        dataSource.setPassword("root");
        dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
        dataSource.setMaximumPoolSize(20);

        return dataSource;
    }

}
```

--------------------------------

### Initialize EasyEntityQuery in a console project

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/startup/quick-start.md

Sets up the EasyEntityQuery instance with a MySQL data source, creates the database if it doesn't exist, and synchronizes the Company and SysUser tables. Uses HikariDataSource for connection pooling and logs SQL to stdout.

```java
package com.easy.query.console;

import com.easy.query.api.proxy.client.DefaultEasyEntityQuery;
import com.easy.query.api.proxy.client.EasyEntityQuery;
import com.easy.query.console.entity.Company;
import com.easy.query.console.entity.SysUser;
import com.easy.query.core.api.client.EasyQueryClient;
import com.easy.query.core.basic.api.database.CodeFirstCommand;
import com.easy.query.core.basic.api.database.DatabaseCodeFirst;
import com.easy.query.core.bootstrapper.EasyQueryBootstrapper;
import com.easy.query.core.logging.LogFactory;
import com.easy.query.mysql.config.MySQLDatabaseConfiguration;
import com.zaxxer.hikari.HikariDataSource;

import javax.sql.DataSource;
import java.util.Arrays;

public class Main {
    private static EasyEntityQuery entityQuery;
    public static void main(String[] args) {
        LogFactory.useStdOutLogging();
        DataSource dataSource = getDataSource();
        EasyQueryClient client = EasyQueryBootstrapper.defaultBuilderConfiguration()
                .setDefaultDataSource(dataSource)
                .optionConfigure(op -> {
                    //Perform a series of optional configurations
                    //op.setPrintSql(true);
                })
                .useDatabaseConfigure(new MySQLDatabaseConfiguration())
                .build();
        entityQuery = new DefaultEasyEntityQuery(client);

        DatabaseCodeFirst databaseCodeFirst = entityQuery.getDatabaseCodeFirst();
        //Create database if it doesn't exist
        databaseCodeFirst.createDatabaseIfNotExists();
        //Automatically synchronize database tables
        CodeFirstCommand codeFirstCommand = databaseCodeFirst.syncTableCommand(Arrays.asList(Company.class, SysUser.class));
        //Execute command
        codeFirstCommand.executeWithTransaction(arg->{
            System.out.println(arg.sql);
            arg.commit();
        });
    }

    /**
     * Initialize data source
     * @return
     */
    private static DataSource getDataSource(){
        HikariDataSource dataSource = new HikariDataSource();
        dataSource.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/eq_db?serverTimezone=GMT%2B8&characterEncoding=utf-8&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true");
        dataSource.setUsername("root");
        dataSource.setPassword("root");
        dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
        dataSource.setMaximumPoolSize(20);

        return dataSource;
    }
}
```

--------------------------------

### 配置 EasyQueryClient 和路由

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/super/sharding-time.md

构建 EasyQueryClient，配置分片相关选项，并应用 ShardingInitializer 和添加路由。

```java
EasyQueryClient easyQueryClient = EasyQueryBootstrapper.defaultBuilderConfiguration()
                .setDefaultDataSource(dataSource)
                .optionConfigure(op -> {
                    op.setDeleteThrowError(false);
                    op.setExecutorCorePoolSize(1);
                    op.setExecutorMaximumPoolSize(0);
                    op.setMaxShardingQueryLimit(10);
                    op.setThrowIfRouteNotMatch(false);
                    op.setMaxShardingRouteCount(512);
                    op.setDefaultDataSourceMergePoolSize(20);
                    //开启定时任务 不然明天的表或者下个月的表不会在内存中存在
                    op.setStartTimeJob(true);
                    op.setReverseOffsetThreshold(10);
                })
                .useDatabaseConfigure(new MySQLDatabaseConfiguration())
                .build();
        DefaultEasyEntityQuery easyEntityQuery = new DefaultEasyEntityQuery(easyQueryClient);
        QueryRuntimeContext runtimeContext = easyQuery.getRuntimeContext();
        QueryConfiguration configuration = runtimeContext.getQueryConfiguration();
        configuration.applyShardingInitializer(new TopicShardingTimeShardingInitializer());
        TableRouteManager tableRouteManager = runtimeContext.getTableRouteManager();
        tableRouteManager.addRoute(new TopicShardingTimeTableRoute());
```

--------------------------------

### Example response with joined commentContent

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/startup/step2.md

Example response showing that commentContent is a comma-separated string produced by the joining function.

```json
{
        "id": "09e8395e-b7f7-48b4-8227-fcbf96c35d1e",
        "title": "夏日旅行攻略",
        "content": "# 这是用户用户D的帖子内容\n包含丰富的文本内容...",
        "userId": "15b6a7c1-3f27-4d21-b67c-9c05cd9bf4b6",
        "publishAt": "2025-08-05T03:09:30.301",
        "userName": "用户D",
        "commentContent": "非常好的分享！,期待更多这样的内容,非常好的分享！"
    },
    {
        "id": "5d40f560-af15-4566-93cd-9359e0a27501",
        "title": "健身计划分享",
        "content": "# 这是用户用户E的帖子内容\n包含丰富的文本内容...",
        "userId": "2ae21dfa-9330-4d8c-bbfa-6b4618c56c45",
        "publishAt": "2025-08-04T08:09:30.301",
        "userName": "用户E",
        "commentContent": "完全同意你的观点,期待更多这样的内容,写得真详细"
    }
```

--------------------------------

### Pagination error example

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/dto-query/question.md

Example showing that LIMIT 10 on a JOIN may return only one user with many papers.

```text
user1 有 10 条 paper

LIMIT 10 可能只返回：user1
```

--------------------------------

### 创建数据库表 help_code 和 sys_user 的 SQL 脚本

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/framework/easy-trans.md

初始化 easy_trans_demo 数据库，创建字典表 help_code 和用户表 sys_user，并插入示例数据。

```sql
CREATE DATABASE IF NOT EXISTS easy_trans_demo CHARACTER SET 'utf8mb4';
USE easy_trans_demo;
create table help_code
(
    code varchar(32) not null comment 'code'primary key,
    type int not null comment '类型',
    name varchar(50) not null comment '中文值'
)comment '字典表';

insert into help_code values('1',1,'男');
insert into help_code values('2',1,'女');
insert into help_code values('3',2,'管理员');
insert into help_code values('4',2,'普通用户');


create table sys_user
(
    id varchar(32) not null comment 'id'primary key,
    name varchar(50) not null comment '姓名',
    sex varchar(50) not null comment '性别',
    type varchar(50) not null comment '用户类型'
)comment '用户表';
insert into sys_user values('1','小明','2','3');
insert into sys_user values('2','小刚','1','4');
```

--------------------------------

### 添加easy-trans依赖

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/framework/easy-trans.md

在pom.xml中添加easy-trans的starter和service依赖，版本为2.2.7。

```xml
<dependency>
     <groupId>com.fhs-opensource</groupId>
    <artifactId>easy-trans-spring-boot-starter</artifactId>
    <version>2.2.7</version>
</dependency>
<dependency>
    <groupId>com.fhs-opensource</groupId>
    <artifactId>easy-trans-service</artifactId>
    <version>2.2.7</version>
</dependency>
```

--------------------------------

### VersionIntStrategy SQL example

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/framework/annotation.md

SQL example for VersionIntStrategy optimistic locking. The update sets version to 2 where version=1, effectively incrementing the version.

```sql
update table set version=2 where id=xxx and version=1
```

--------------------------------

### Solon application configuration and startup

Source: https://github.com/xuejmnet/easy-query-doc/blob/main/src/en/guide/solon.md

YAML configuration for the db1 data source, easy-query settings, and logging. Includes a Java main class that starts Solon and loads the configuration file.

```yaml
# Add configuration file
db1:
  jdbcUrl: jdbc:mysql://127.0.0.1:3306/easy-query-test?serverTimezone=GMT%2B8&characterEncoding=utf-8&useSSL=false&allowMultiQueries=true&rewriteBatchedStatements=true
  username: root
  password: root
  driver-class-name: com.mysql.cj.jdbc.Driver


easy-query: 
  # Configure custom log
  # log-class: ...
  db1:
    # Supports mysql pgsql h2 mssql dameng mssql_row_number kingbase_es, other databases are being adapted
    database: mysql
    # Supports underlined default lower_camel_case upper_camel_case upper_underlined
    name-conversion: underlined
    # Throw exception on physical deletion, not including manual SQL
    delete-throw: true

# Logger level configuration example
solon.logging.logger:
  "root": #Default logger configuration
    level: TRACE
  "com.zaxxer.hikari":
    level: WARN
```

```java
public class Main {
    public static void main(String[] args) {
        Solon.start(Main.class,args,(app)->{
            app.cfg().loadAdd("application.yml");
        });
    }
}

//Access URL http://localhost:8080/test/hello

//Returns Hello World
```
Tokens:
Raw