You are asked to speed up a read-heavy list endpoint that currently loads mapped entities and maps them to a response in Java. Walk through converting it to a DTO read path and what you have to watch out for.

## Why the entity read is the bottleneck here A list endpoint that loads entities pays for everything the ORM offers and uses almost none of it: all mapped columns are selected, each row becomes an instance plus a loaded-state snapshot held by the persistence context, and every flush in the transaction dirty-checks the lot. Worse, mapping to a response in Java tends to navigate associations, and each navigation on a lazily mapped association is another statement — the same trip repeated per row. ## The conversion, step by step ### 1. Derive the select list from the payload Open the response class or the serialised JSON and write down the fields. That set — not the entity's field list — is the query. If the payload has `id, title, authorName, commentCount`, the query has four expressions, one of which is an aggregate and one of which comes from a join. ### 2. One query per use case Write a dedicated DTO (a record is ideal) and a constructor expression: ``` select new com.app.PostRow(p.id, p.title, a.name, count(c)) from Post p join p.author a left join p.comments c where p.published = true group by p.id, p.title, a.name ``` Resist a single "wide" DTO shared across endpoints that each query half-fills — half-populated objects are as confusing as partially initialised entities. ### 3. Push work down Everything the database does better belongs in the query: predicates, `order by`, `limit`/`offset` (`setFirstResult`/`setMaxResults`), aggregates, and existence checks. A projection that fetches everything and then filters, sorts or counts in Java has moved the cost, not removed it. Where paging plus aggregation gets awkward, a second lightweight count query is usually cheaper than materialising the world. ### 4. Remove, do not layer Delete the entity query and the entity→response mapper. A common failed conversion keeps loading entities "because something might need them" and adds the projection alongside, doubling the work. ### 5. Verify the shape of the traffic After the change the endpoint should issue a predictable, constant number of statements: ideally one, plus a count query for paging. If statement count still scales with page size, some navigation survived. Compare wall-clock and allocation for a realistic page size, not for ten rows. ## What breaks, and how to handle it **Behaviour that lived on the entity.** `post.getDisplayTitle()` or a computed status may be a method on the mapped class. Options: re-express it in SQL, compute it inside the DTO from selected values (a record can have extra derived accessors), or keep it in a small mapper that takes the DTO. What you must not do is load the entity just to call the method — that reinstates the cost. **Collections.** A constructor expression cannot take `p.comments`. If the payload nests children, run a second query for the child rows filtered by the collected parent ids and stitch them by id in memory; that is two statements regardless of page size, and it avoids the duplicated-parent-row problem a join produces. Hibernate 6's `multiset()` function can build nested lists in one statement when you want it. **Lazy navigation you relied on.** With entities, a missing field was silently fetched. With DTOs it is simply absent, which is a feature: absence is a compile-time visible gap, not a runtime statement storm. **Authorisation and auditing.** If a check read fields from the loaded entity, those fields must appear in the projection or the predicate must move into the `where` clause. Filtering rows in SQL is usually the better outcome anyway. **Second-level caching.** If those entities were served from a cache, the DTO query goes to the database every time unless you cache the query results. Measure rather than assume the projection wins. **Tests.** Tests that asserted on returned entities need rewriting against the DTO, and because JPQL constructor expressions are strings, each new query needs a test that actually executes it — a mismatched constructor is a runtime failure. ## Keep the write path on entities The conversion applies to reads. Commands should still load the managed entity by id and mutate it, because dirty checking, cascades, versioning and lifecycle callbacks are exactly what you want there. The result is a read side of query-shaped types and a write side of mapped entities — the same idea in the small as a CQRS split, without any of its infrastructure. ## When not to convert A detail page returning one row, a lookup served from cache, or a screen that immediately edits what it loaded are all fine as entity reads. Convert the endpoints where result size, column width or statement count actually hurt, and leave the rest alone; a repository full of near-identical projections has its own maintenance cost.