easy-query: A Modern, Type-Safe ORM for Java That Actually Makes Sense

// JPA Criteria API - Runtime strings, no type safety
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<User> cq = cb.createQuery(User.class);
Root<User> user = cq.from(User.class);
cq.where(cb.and(
    cb.equal(user.get("name"), "John"),  // String reference!
    cb.greaterThan(user.get("age"), 18)  // Typo? Find out at runtime!
));

// easy-query - Compile-time safety, fluent API
List<User> users = easyEntityQuery.queryable(User.class)
    .where(user -> {
        user.name().eq("John");   // Full IntelliSense support
        user.age().gt(18);        // Typo? Compiler catches it!
    })
    .toList();

// ❌ Old way - Runtime errors waiting to happen
query.where("userNam = ?", name);  // Typo in field name!

// ✅ easy-query - Compiler catches typos
List<User> users = easyEntityQuery.queryable(User.class)
    .where(user -> user.userName().eq(name))  // IDE autocomplete!
    .toList();

// Complex query that's still readable
List<Order> orders = easyEntityQuery.queryable(Order.class)
    .where(order -> {
        order.status().eq("ACTIVE");
        order.amount().between(100, 1000);
        order.createTime().ge(LocalDateTime.now().minusDays(30));
    })
    .orderBy(order -> order.createTime().desc())
    .limit(10)
    .toList();

// Load user with roles and company in efficient batched queries
List<User> users = easyEntityQuery.queryable(User.class)
    .include(user -> user.roles())      // Batched query #1
    .include(user -> user.company())    // Batched query #2
    .toList();

// Executed SQL:
// Query 1: SELECT * FROM user
// Query 2: SELECT * FROM user_role WHERE user_id IN (1,2,3,...)
// Query 3: SELECT * FROM role WHERE id IN (10,11,12,...)
// Query 4: SELECT * FROM company WHERE id IN (100,101,...)

@Data
public class UserSummaryDTO {
    private String userId;
    private String fullName;
    private String companyName;
    private int roleCount;
}

// Type-safe mapping
List<UserSummaryDTO> summaries = easyEntityQuery.queryable(User.class)
    .include(user -> user.roles())
    .include(user -> user.company())
    .select(user -> new UserSummaryDTOProxy()
        .userId().set(user.id())
        .fullName().set(user.firstName().concat(" ").concat(user.lastName()))
        .companyName().set(user.company().name())
        .roleCount().set(user.roles().count())
    )
    .toList();

// Monthly sales statistics
List<SalesStatDTO> stats = easyEntityQuery.queryable(Order.class)
    .where(order -> order.status().eq("COMPLETED"))
    .groupBy(order -> GroupKeys.of(
        order.userId(),
        order.createTime().format("yyyy-MM")
    ))
    .select(SalesStatDTO.class, group -> Select.of(
        group.key1().as(SalesStatDTO::getUserId),
        group.key2().as(SalesStatDTO::getMonth),
        group.count().as(SalesStatDTO::getOrderCount),
        group.sum(s -> s.amount()).as(SalesStatDTO::getTotalAmount),
        group.avg(s -> s.amount()).as(SalesStatDTO::getAvgAmount),
        group.max(s -> s.amount()).as(SalesStatDTO::getMaxAmount)
    ))
    .having(group -> group.count().gt(5L))
    .orderBy(SalesStatDTO::getTotalAmount, false)
    .toList();

// Generated SQL:
// SELECT 
//     user_id,
//     DATE_FORMAT(create_time, '%Y-%m') as month,
//     COUNT(*) as order_count,
//     SUM(amount) as total_amount,
//     AVG(amount) as avg_amount,
//     MAX(amount) as max_amount
// FROM t_order
// WHERE status = 'COMPLETED'
// GROUP BY user_id, DATE_FORMAT(create_time, '%Y-%m')
// HAVING COUNT(*) > 5
// ORDER BY total_amount DESC

try (TrackContext track = easyQueryClient.startTrack()) {
    User user = easyEntityQuery.queryable(User.class)
        .whereById("1")
        .firstOrNull();

    user.setName("John Doe");
    user.setEmail("[email protected]");

    track.saveChanges();  // Only updates changed fields!
}

// Generated SQL:
// UPDATE t_user SET name = ?, email = ? WHERE id = ?
// Only the modified fields are in the UPDATE statement

// Bulk update
long updated = easyEntityQuery.updatable(User.class)
    .set(user -> {
        user.status().set("INACTIVE");
        user.updateTime().set(LocalDateTime.now());
    })
    .where(user -> user.lastLoginTime().lt(LocalDateTime.now().minusDays(90)))
    .executeRows();

// Bulk delete
long deleted = easyEntityQuery.deletable(Order.class)
    .where(order -> {
        order.status().eq("CANCELLED");
        order.createTime().lt(LocalDateTime.now().minusYears(2));
    })
    .executeRows();

// Three-table join with conditions
List<OrderDetailDTO> details = easyEntityQuery.queryable(Order.class)
    .leftJoin(User.class, (order, user) -> 
        order.userId().eq(user.id())
    )
    .leftJoin(Product.class, (order, user, product) -> 
        order.productId().eq(product.id())
    )
    .where((order, user, product) -> {
        order.status().eq("COMPLETED");
        user.vipLevel().gt(3);
        product.category().eq("Electronics");
    })
    .select((order, user, product) -> new OrderDetailDTOProxy()
        .orderId().set(order.id())
        .userName().set(user.name())
        .productName().set(product.name())
        .totalPrice().set(order.quantity().multiply(product.price()))
    )
    .toList();

// Step 1: Annotate your entity
@Table("t_user")
@EntityProxy  // ← This is all you need!
@Data
public class User {
    @Column(primaryKey = true)
    private String id;
    private String name;
    private String email;
    private Integer age;

    @Navigate(value = RelationTypeEnum.ManyToMany, ...)
    private List<Role> roles;
}

// Step 2: Proxy is auto-generated
// You get UserProxy with type-safe methods:
// - user.id() → SQLStringTypeColumn<UserProxy>
// - user.name() → SQLStringTypeColumn<UserProxy>
// - user.age() → SQLIntTypeColumn<UserProxy>
// - user.roles() → Navigation methods

// Step 3: Use it!
List<User> adults = easyEntityQuery.queryable(User.class)
    .where(user -> user.age().ge(18))  // Full type safety!
    .toList();

// Find users who have more than 5 completed orders
List<User> activeUsers = easyEntityQuery.queryable(User.class)
    .where(user -> {
        user.id().in(
            easyEntityQuery.queryable(Order.class)
                .where(order -> order.status().eq("COMPLETED"))
                .groupBy(order -> GroupKeys.of(order.userId()))
                .having(group -> group.count().gt(5L))
                .select(order -> order.userId())
        );
    })
    .toList();

// Build queries dynamically
public List<User> searchUsers(String name, Integer minAge, String city) {
    return easyEntityQuery.queryable(User.class)
        .where(user -> {
            user.name().like(name != null, name);  // Only if name provided
            user.age().ge(minAge != null, minAge); // Only if minAge provided
            user.city().eq(city != null, city);    // Only if city provided
        })
        .toList();
}

// Built-in pagination support
EasyPageResult<User> page = easyEntityQuery.queryable(User.class)
    .where(user -> user.status().eq("ACTIVE"))
    .orderBy(user -> user.createTime().desc())
    .toPageResult(1, 20);  // page 1, 20 items per page

System.out.println("Total: " + page.getTotal());
System.out.println("Data: " + page.getData());

// Built-in sharding for high-traffic apps!
@Table(value = "t_order", shardingInitializer = MonthTableShardingInitializer.class)
@EntityProxy
public class Order {
    @Column(primaryKey = true)
    private String id;

    @ShardingTableKey  // Sharding key
    private LocalDateTime createTime;

    private BigDecimal amount;
}

// Query automatically routes to correct sharded tables
List<Order> orders = easyEntityQuery.queryable(Order.class)
    .where(order -> 
        order.createTime().between(
            LocalDateTime.of(2024, 1, 1, 0, 0),
            LocalDateTime.of(2024, 3, 31, 23, 59)
        )
    )
    .toList();

// Executes across multiple tables in parallel:
// t_order_202401, t_order_202402, t_order_202403

// Easy to switch databases
EasyQueryClient easyQueryClient = EasyQueryBootstrapper
    .defaultBuilderConfiguration()
    .setDefaultDataSource(dataSource)
    .optionConfigure(op -> {
        op.setDatabase(DatabaseType.MYSQL);  // Just change this!
    })
    .build();

<dependency>
    <groupId>com.easy-query</groupId>
    <artifactId>sql-springboot-starter</artifactId>
    <version>3.1.49</version>
</dependency>

<!-- Annotation processor for code generation -->
<dependency>
    <groupId>com.easy-query</groupId>
    <artifactId>sql-processor</artifactId>
    <version>3.1.49</version>
    <scope>provided</scope>
</dependency>

# application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: password

easy-query:
  enable: true
  database: mysql
  print-sql: true
  name-conversion: underlined  # camelCase → snake_case

@Table("t_user")
@EntityProxy  // Enable code generation
@Data
public class User {
    @Column(primaryKey = true)
    private String id;
    private String name;
    private String email;
    private Integer age;
    private LocalDateTime createTime;
}

@Service
public class UserService {
    @Resource
    private EasyEntityQuery easyEntityQuery;

    public List<User> getActiveUsers() {
        return easyEntityQuery.queryable(User.class)
            .where(user -> {
                user.status().eq("ACTIVE");
                user.age().ge(18);
            })
            .orderBy(user -> user.createTime().desc())
            .toList();
    }
}

@Service
@RequiredArgsConstructor
public class OrderService {
    private final EasyEntityQuery easyEntityQuery;

    // Complex query with joins and aggregation
    public List<OrderStatDTO> getMonthlyStats(String userId, int year) {
        return easyEntityQuery.queryable(Order.class)
            .where(order -> {
                order.userId().eq(userId);
                order.createTime().format("yyyy").eq(String.valueOf(year));
                order.status().eq("COMPLETED");
            })
            .groupBy(order -> GroupKeys.of(
                order.createTime().format("yyyy-MM")
            ))
            .select(OrderStatDTO.class, group -> Select.of(
                group.key1().as(OrderStatDTO::getMonth),
                group.count().as(OrderStatDTO::getOrderCount),
                group.sum(s -> s.totalAmount()).as(OrderStatDTO::getTotalSales)
            ))
            .orderBy(OrderStatDTO::getMonth, true)
            .toList();
    }

    // Query with navigation properties
    public OrderDetailVO getOrderDetail(String orderId) {
        Order order = easyEntityQuery.queryable(Order.class)
            .whereById(orderId)
            .include(o -> o.orderItems())  // Load items
            .include(o -> o.user())        // Load user
            .include(o -> o.shipping())    // Load shipping
            .firstOrNull();

        if (order == null) {
            throw new OrderNotFoundException(orderId);
        }

        return OrderDetailVO.from(order);
    }

    // Pagination
    public EasyPageResult<OrderListDTO> searchOrders(
        OrderSearchRequest request, int page, int size
    ) {
        return easyEntityQuery.queryable(Order.class)
            .where(order -> {
                order.userId().eq(request.getUserId() != null, request.getUserId());
                order.status().eq(request.getStatus() != null, request.getStatus());
                order.createTime().ge(request.getStartDate() != null, request.getStartDate());
                order.createTime().le(request.getEndDate() != null, request.getEndDate());
            })
            .orderBy(order -> order.createTime().desc())
            .select(OrderListDTO.class)
            .toPageResult(page, size);
    }

    // Bulk update
    @Transactional
    public long cancelExpiredOrders() {
        return easyEntityQuery.updatable(Order.class)
            .set(order -> {
                order.status().set("CANCELLED");
                order.cancelTime().set(LocalDateTime.now());
            })
            .where(order -> {
                order.status().eq("PENDING");
                order.createTime().lt(LocalDateTime.now().minusHours(24));
            })
            .executeRows();
    }
}

// 1. Add dependencies (see above)
// 2. Configure database (see above)
// 3. Create your first entity:

@Table("t_blog")
@EntityProxy
@Data
public class Blog {
    @Column(primaryKey = true)
    private String id;
    private String title;
    private String content;
    private Integer views;
    private LocalDateTime publishTime;
}

// 4. Start querying:

@Service
public class BlogService {
    @Resource
    private EasyEntityQuery easyEntityQuery;

    public List<Blog> getPopularBlogs() {
        return easyEntityQuery.queryable(Blog.class)
            .where(blog -> blog.views().gt(1000))
            .orderBy(blog -> blog.publishTime().desc())
            .limit(10)
            .toList();
    }
}