Easy-Query ORM

Easy-Query is a Java ORM framework based on APT proxy pattern, providing type-safe Lambda query syntax. This skill covers core concepts, common operations, relationship mapping, and advanced features.

Core Concepts

Proxy Pattern

Easy-Query uses APT (Annotation Processing Tool) to generate proxy classes at compile time, enabling type-safe query syntax.

Entity Proxy (@EntityProxy):

@Table("t_blog")
@EntityProxy
public class BlogEntity implements ProxyEntityAvailable<BlogEntity, BlogEntityProxy> {
    private String title;
    private BigDecimal score;
}

VO Proxy (@EntityFileProxy):

@EntityFileProxy
public class BlogVO {
    private String title;
    private BigDecimal avgScore;
}

Proxy Class Generation Requirements

After using @EntityProxy or @EntityFileProxy annotations, you must compile the project first to generate proxy classes:

mvn clean compile

Generated proxy classes are located at: target/generated-sources/annotations/

Lambda Field References

When querying, you must use Lambda expressions with proxy objects to access fields:

// ✅ Correct: Using Lambda expression
easyEntityQuery.queryable(BlogEntity.class)
    .where(b -> b.title().like("Spring%"))
    .toList();

// ❌ Incorrect: Directly using getter method
easyEntityQuery.queryable(BlogEntity.class)
    .where(b -> b.getTitle().like("Spring%")) // Compilation error

Quick Reference

CRUD Operations Cheat Sheet

Operation	Method	Example
Query Single	firstOrNull()	.where(b -> b.id().eq("123")).firstOrNull()
Query List	toList()	.where(b -> b.score().gt(3.0)).toList()
Insert	insertable()	easyEntityQuery.insertable(entity).executeRows()
Expression Update	updatable().setColumns()	.setColumns(b -> b.title().set("New Title"))
Entity Update	updatable(entity)	easyEntityQuery.updatable(entity).executeRows()
Delete	deletable()	.where(b -> b.score().lt(1.0)).executeRows()

Join Operations Cheat Sheet

Type	Method	Use Case
Left Join	.leftJoin(Class, (a,b) -> condition)	Keep all left table data
Inner Join	.innerJoin(Class, (a,b) -> condition)	Return only matched data
Right Join	.rightJoin(Class, (a,b) -> condition)	Keep all right table data

Relationship Types Cheat Sheet

Annotation Value	Relationship Type	Example
OneToOne	One-to-One	User ↔ Profile
OneToMany	One-to-Many	Topic → Multiple Blogs
ManyToOne	Many-to-One	Blog →所属 Topic
ManyToMany	Many-to-Many	Student ↔ Course

Common Operation Patterns

Basic Queries

// Single record query
BlogEntity blog = easyEntityQuery.queryable(BlogEntity.class)
    .where(b -> b.id().eq("123"))
    .firstOrNull();

// Multi-condition query
List<BlogEntity> blogs = easyEntityQuery.queryable(BlogEntity.class)
    .where(b -> {
        b.title().like("Easy%");
        b.score().gt(new BigDecimal("3.0"));
    })
    .orderBy(b -> b.publishTime().desc())
    .toList();

Multi-Table Join

// Left Join
easyEntityQuery.queryable(Topic.class)
    .leftJoin(BlogEntity.class, (t, b) -> t.id().eq(b.id()))
    .where((t, b) -> {
        t.id().eq("123");
        b.title().isNotNull();
    })
    .toList();

Differential Update

TrackManager trackManager = easyEntityQuery.getRuntimeContext().getTrackManager();
try {
    trackManager.begin();
    BlogEntity blog = easyEntityQuery.queryable(BlogEntity.class)
        .asTracking()
        .whereById("123").firstNotNull();
    blog.setViewCount(blog.getViewCount() + 1);
    easyEntityQuery.updatable(blog).executeRows();
} finally {
    trackManager.release();
}

Pagination Query

EasyPageResult<BlogEntity> pageResult = easyEntityQuery.queryable(BlogEntity.class)
    .where(b -> b.status().eq(1))
    .orderBy(b -> b.publishTime().desc())
    .toPageResult(1, 20);

long total = pageResult.getTotalCount();
List<BlogEntity> list = pageResult.getList();

VO Query Mapping

// Define VO
@EntityFileProxy
public class BlogVO {
    private String title;
    private BigDecimal avgScore;
}

// Use VO to receive results
List<BlogVO> vos = easyEntityQuery.queryable(BlogEntity.class)
    .groupBy(b -> b.category())
    .select(g -> new BlogVOProxy()
        .title().set(g.key())
        .avgScore().set(g.groupTable().score().avg())
    )
    .toList();

Relationship Mapping Configuration

Use @Navigate annotation to define relationships between entities:

// One-to-Many
@Navigate(value = RelationTypeEnum.OneToMany,
          selfProperty = "id",
          targetProperty = "topicId")
private List<BlogEntity> blogs;

// Many-to-One
@Navigate(value = RelationTypeEnum.ManyToOne,
          selfProperty = "topicId",
          targetProperty = "id")
private Topic topic;

// One-to-One
@Navigate(value = RelationTypeEnum.OneToOne,
          selfProperty = "id",
          targetProperty = "userId")
private UserProfile profile;

Advanced Features Overview

Implicit Join

Automatically handles OneToOne/ManyToOne relationships without explicit join:

// Automatically generates LEFT JOIN
easyEntityQuery.queryable(SysUser.class)
    .where(u -> u.company().name().like("Alibaba"))
    .toList();

Implicit Subquery

Automatically handles OneToMany/ManyToMany relationships:

// Automatically generates EXISTS subquery
easyEntityQuery.queryable(Company.class)
    .where(c -> c.users().any(u -> u.name().like("Xiaoming")))
    .toList();

Aggregation Query

easyEntityQuery.queryable(BlogEntity.class)
    .where(b -> b.score().gt(new BigDecimal("3.0")))
    .groupBy(b -> GroupKeys.of(b.category()))
    .select(g -> Select.DRAFT.of(
        g.key1(),
        g.groupTable().score().avg(),
        g.groupTable().id().count()
    ))
    .toList();

Common Issues Cheat Sheet

Issue	Solution
Cannot find XXXProxy class	Run mvn clean compile to generate proxy classes
@Column mapping not working	VO needs to use the same column name mapping
Circular reference serialization issues	Use select to specify fields when querying or add JSON ignore annotations
Slow Join query performance	Optimize with subQueryToGroupJoin = true

Complete Resources

Detailed Documentation

• references/advanced-features.md - Five implicit features explained in detail (Implicit Join/Subquery/Grouping/Partition/CASE WHEN)
• references/relationship-mapping.md - Complete @Navigate annotation configuration and best practices
• references/performance-optimization.md - Performance optimization tips and common pitfalls

Working Examples

• examples/BlogEntity.java - Complete entity class example
• examples/QueryExamples.java - Various query operation examples
• examples/JoinExamples.java - Multi-table Join examples
• examples/TrackingUpdateExample.java - Complete differential update example

Core Annotation Locations

• @EntityProxy / @EntityFileProxy: sql-core/src/main/java/com/easy/query/core/annotation/
• @Table / @Column: sql-core/src/main/java/com/easy/query/core/annotation/
• @Navigate: sql-core/src/main/java/com/easy/query/core/annotation/
• ProxyEntityAvailable: sql-platform/sql-api-proxy/src/main/java/com/easy/query/core/proxy/