In JPA/Hibernate, how do you make a JPQL/HQL query return instances of your own DTO class instead of managed entity objects, and what must that class provide?

## What a projection is `select u from User u` tells the provider to select every mapped column of the entity, build a `User` instance, and register it in the persistence context as a **managed** object. A *projection* selects individual expressions instead — `u.id`, `u.name`, `count(o)` — and hands you the values. A **DTO projection** wraps those values in a class you control, one shaped for the caller (an HTTP response, a report row) rather than for the database table. ## Constructor expressions The standard mechanism is the constructor expression, part of JPQL since JPA 1.0: ``` select new com.app.UserSummary(u.id, u.name, u.address.city) from User u where u.active = true ``` Mechanically, the provider emits SQL selecting exactly those three columns, then for each row calls `new UserSummary(...)` with the converted values. Requirements: - **Fully qualified class name.** JPQL has no import mechanism, so `new UserSummary(...)` fails unless the provider is configured to resolve short names (Hibernate 6 allows registering imports; do not rely on it in portable code). - **A matching constructor.** Parameter count, order, and assignable types must line up. A `Long` id against an `int` parameter or two swapped `String` parameters is a runtime failure, not a compile-time one — the query is a string. - **Scalar arguments only.** You can pass entity-valued paths in Hibernate, but you cannot pass a collection: `new Dto(u.id, u.orders)` is invalid. Nested one-to-many data needs either a second query keyed by the parent ids, or Hibernate 6's `multiset()` HQL function. - The DTO does not need to be an entity, does not need a no-arg constructor, and should not be annotated with `@Entity`. ## Newer conveniences Jakarta Persistence 3.2 and Hibernate 6.3+ added **implicit instantiation**: `em.createQuery("select u.id, u.name from User u", UserSummary.class)` will find a constructor matching the select list. Java **records** are ideal DTO carriers — the canonical constructor matches the component order, and immutability suits a read model. Hibernate also offers `jakarta.persistence.Tuple` and raw `Object[]` when you do not want a class per query, and Hibernate 6 replaced the old `ResultTransformer` with `TupleTransformer`/`ResultListTransformer` for custom assembly. ## Why it matters: the results are detached values The objects a constructor expression produces are ordinary Java objects. Hibernate does not put them in the persistence context, does not keep a loaded-state snapshot of them, and never dirty-checks them at flush. Consequences: - Changing a field on the DTO changes nothing in the database. Candidates who expect an update here misunderstand the model. - There is no lazy loading. Anything not in the select list is simply absent; you cannot navigate from a DTO to an unselected association, and you will never see a lazy-initialization failure from one. - To *write*, you must load the entity by id (or run a bulk `update` statement). A DTO is a read artifact. ## A worked contrast ```java // managed read: all columns, entity in the persistence context, snapshot retained List<User> users = em.createQuery("from User u", User.class).getResultList(); // DTO read: two columns, nothing retained List<UserSummary> rows = em.createQuery( "select new com.app.UserSummary(u.id, u.name) from User u", UserSummary.class) .getResultList(); ``` The second form usually emits a narrower `select`, transfers fewer bytes, allocates one small object per row instead of an entity plus its state snapshot, and adds nothing to later flush cost. ## Practical notes Keep one DTO per read use case rather than a shared "wide" DTO that every query half-fills — half-populated DTOs are as confusing as partially initialised entities. Because the query is a string, cover each constructor expression with a test that actually executes it; a renamed constructor parameter type is otherwise found in production. And name the DTO for the *view* it serves (`UserSummary`, `InvoiceRow`), not for the entity, so nobody mistakes it for a second mapping of the table.