Model Query

At a glance

Model Query is an open-source Java library (Apache 2.0) for reading JPA data straight into DTOs or records. You annotate a record with @QueryModel(root = SomeEntity.class). An annotation processor then generates a typed Q class, such as QOrderView, that you use to filter, sort, page and export. Version 0.11.1 was the latest release on 2026-11-03.

Good fit

It suits Java teams on Hibernate 6.6 or later who keep writing projection queries for list screens, paged APIs and exports. One record defines both the query shape and the result type. If a filter value is an empty Optional, that filter adds no condition, so request-driven search filters stay short. A generated fields() method maps ?fields=id,customer.name style requests to a typed selection.

Consider something else when

Skip it if you need a stable API now. Every public type is marked incubating and can change in a minor release until the 1.0 freeze. It also requires Java 17+ and Jakarta Persistence 3.1+, and the stated requirements name Hibernate ORM 6.6+, which leaves out older stacks. Vendor-aware behaviour covers H2, PostgreSQL and MySQL, behind an SPI other databases can implement.

Start here

In a Maven build, import io.github.rey5137:model-query-bom at 0.11.1. Add model-query-jpa and model-query-annotations, then register model-query-processor under annotationProcessorPaths. On Spring Boot 3.4+, use model-query-spring-boot-starter in place of the first two but keep the processor. The build has worked when a Q class appears for your annotated record. The repository's plain-JPA sample shows a 19-line quick start.

Cost and requirements

The library is free under the Apache 2.0 licence. It needs Java 17 or later, Jakarta Persistence 3.1+ and Hibernate ORM 6.6+. The README says it was tested on Hibernate 6.6 and 7.x. The Spring Boot starter needs Spring Boot 3.4+ and pulls in Spring Data JPA, Hibernate and model-query-hibernate. Setup instructions cover Maven only. Vendor-aware behaviour covers H2, PostgreSQL and MySQL, behind an SPI other databases can implement.

Limits to know

The project has three listed contributors, one of them Claude. On top of the library-wide incubating status, the write features (bulk updates and deletes, inserts, entity writes that run callbacks and audit listeners, and selected-field tracking) each carry their own @Incubating label. The project's own documentation compares it with plain JPA, Querydsl and Blaze-Persistence, so read that page before choosing among them.

Still unclear

• Does the annotation processor work with Gradle? The setup instructions cover only Maven.
• Can it run on a JPA provider other than Hibernate, such as EclipseLink, given that the requirements name Hibernate ORM 6.6+?
• How do its generated SQL and export performance compare with Querydsl or Blaze-Persistence on large datasets?
• How often have breaking API changes landed between minor releases so far?