In JPA, what is a named query, how do you declare one with the @NamedQuery annotation, and how do you execute it through the EntityManager?

## What a named query is A named query is a query string declared **once**, as metadata of the persistence unit, under a name — and then executed by that name. It is not a different query language: the string is ordinary JPQL (or HQL, Hibernate's superset). What changes is *where the text lives* and *when it is processed*. Declaration normally sits on an entity class: ```java @Entity @NamedQuery(name = "Book.findByAuthor", query = "select b from Book b where b.author = :author order by b.title") public class Book { ... } ``` The annotation is repeatable in modern JPA; older code groups several inside `@NamedQueries({ ... })`. The same declarations can be written in XML instead (`orm.xml`), which is how teams keep long SQL/JPQL out of Java source. ## Executing one ```java TypedQuery<Book> q = em.createNamedQuery("Book.findByAuthor", Book.class); q.setParameter("author", author); q.setMaxResults(20); List<Book> books = q.getResultList(); ``` `createNamedQuery(String)` returns an untyped `Query`; the two-argument overload returns a `TypedQuery<T>` and is what you should use. If the name does not exist, you get an `IllegalArgumentException` at that call. A `Query` object is **stateful and not thread-safe** — you create a fresh one per execution; what is shared and reused is the *compiled plan* behind the name, not the `Query` instance. ## The name is a global namespace The single most common surprise: the name is **not** scoped to the entity class the annotation happens to sit on. All named queries in a persistence unit share one flat namespace. Declaring `"findAll"` on two entities is a duplicate-name error when the persistence unit boots. The universal convention `EntityName.queryName` exists purely to partition that namespace by hand. ## Startup parsing, and why it matters When the persistence unit is built, each named **JPQL** query is parsed, its entity and attribute references are resolved against the mapping metadata, and it is translated to SQL. A misspelled attribute, a renamed field, a syntax error — all surface as a startup failure with the query name in the message. Inline `createQuery("...")` strings get none of that: they fail the first time that code path executes, which may be in production, on a rare branch. That validation is also *why* named queries are cheap at runtime. The plan is already in the query-plan cache, so execution is: fetch plan, bind parameters, run JDBC. An inline string has to be looked up in the plan cache by its full text (a hash of the string) and translated on first miss. The same guarantee does **not** extend to `@NamedNativeQuery`. Native SQL is opaque to the provider — it cannot know your database's dialect quirks or whether a table exists — so a named native query is registered but not verified. It fails when it runs. ## Parameters and result shape Named queries support named parameters (`:author`) and positional ones (`?1`); named parameters are the norm because the declaration and the call site are far apart, so a positional index is easy to get wrong. The result class is supplied at the call site via `createNamedQuery(name, Book.class)`. Newer JPA revisions also allow declaring `resultClass` on the annotation itself, which lets the provider check the projection at boot too. ## Extras carried on the declaration `@NamedQuery` can carry a `lockMode` and an array of `@QueryHint`s, so caching, fetch size, timeout or a pessimistic lock become part of the declaration rather than something every call site must remember to set. That is a real argument for the style: the *policy* travels with the query. ## Trade-offs Against: the query text is far from the code that uses it, so reading a call site tells you nothing about what runs; refactoring tools help less; and the flat namespace invites collisions. Dynamic predicates cannot be expressed at all — a query whose WHERE clause varies with user input belongs in the Criteria API, not in a named query, and string-concatenating a named query defeats the whole point. For: startup validation, one place to review and tune, hints attached to the declaration, and an obvious inventory of every query the application can issue — which is genuinely useful during a schema change or a performance audit.