Beyond holding the query text, a JPA @NamedQuery declaration can carry query hints and a lock mode. What can you attach there, and why would you prefer attaching it to the declaration over setting it at each call site?

## The declaration is a place to put policy A query has two halves: *what to fetch* (the JPQL) and *how to execute it* (timeout, fetch size, caching, locking, read-only). Inline queries force the second half onto each call site, where it is forgotten, copied inconsistently, or quietly dropped during a refactor. A named query declaration can carry both. ```java @NamedQuery(name = "...", query = "...", lockMode = LockModeType.PESSIMISTIC_WRITE, hints = { @QueryHint(name = "...", value = "...") }) ``` ## Hints worth knowing **`org.hibernate.readOnly = true`.** Entities returned are loaded into the persistence context *without* a loaded-state snapshot. Two consequences: dirty checking cannot flag them, so no accidental UPDATE can be generated from an incidental setter call, and memory per entity drops roughly by the size of the second copy of its state. For report-style queries that pull thousands of rows and only read them, this is the single highest-value hint. Note it changes semantics — modifications to those entities will not be persisted, which is the point but surprises people. **`org.hibernate.fetchSize`.** Sets the JDBC statement fetch size — how many rows the driver pulls per round trip. Drivers differ wildly: some default to fetching everything into client memory, and a fetch size is the difference between a streaming scan and an out-of-memory error. Pairing this with read-only is the standard shape for a large scan. **Timeouts.** `jakarta.persistence.query.timeout` (milliseconds) is the portable one; there is a Hibernate-specific equivalent in seconds. It bounds a runaway query rather than letting it hold a connection indefinitely. `jakarta.persistence.lock.timeout` bounds how long a pessimistic lock request waits. **`org.hibernate.cacheable = true`** enrols the query in the **query cache** (which caches the *identifiers* a query returned, not the entities themselves, and which requires the second-level cache to be usable at all). `org.hibernate.cacheRegion` names the region. This is a hint you attach only when the query is genuinely repetitive over stable data; wiring it in at some call sites and not others is exactly the inconsistency the declaration prevents. **`org.hibernate.comment`** injects a comment into the generated SQL (when SQL comments are enabled). In a database's slow-query log or monitoring view, the emitted SQL is otherwise anonymous; a comment naming the query is often what turns a mystery statement into a five-minute fix. Cheap and underused. **Flush mode** can also be pinned, which matters for queries that must not trigger an automatic flush of pending changes. ## lockMode on the declaration `lockMode = LockModeType.PESSIMISTIC_WRITE` makes the query acquire row locks as part of executing, rather than requiring the caller to call `setLockMode` or a separate lock request. Where the query *is* the read side of a read-modify-write sequence, encoding that in the declaration is a correctness improvement: the guarantee no longer depends on every author of every call site knowing the protocol. The flip side is that the lock becomes invisible at the call site, so someone reusing the query for a harmless read now takes write locks and can create contention or deadlocks. The mitigation is naming: a query that locks should say so in its name. ## Why declaration beats call site 1. **No call site can forget.** The policy is not opt-in per caller. 2. **Consistency.** Every caller gets the same fetch size and timeout, so behaviour is reproducible and a tuning change is one edit. 3. **Reviewability.** A reviewer looking at the query declaration sees both the shape and the execution policy together. With inline queries, finding out whether a query is cached means grepping the call sites. 4. **It composes with externalisation.** Hints in `orm.xml` can be tuned per environment without touching Java. ## Limits and cautions - **Unknown hints are ignored, silently.** JPA specifies that a provider must ignore hints it does not recognise. A misspelt hint name is not an error; it simply does nothing. This is a real trap — verify with SQL logging or metrics rather than trusting the annotation. - **Call sites can still override.** Setting a hint on the returned `Query` takes effect for that execution, so the declaration is a default rather than a guarantee. - **Hints are not portable.** `org.hibernate.*` names bind you to Hibernate; only the `jakarta.persistence.*` ones are specified. - **Do not turn hints into a tuning junk drawer.** Each hint should have a reason someone can state; a caching hint on a query over volatile data is worse than none. ## The shape of a good answer Name two or three hints you have actually used, say what problem each solved (memory on large scans, an unbounded query holding a connection, an unidentifiable statement in the slow-query log), and make the general point: the declaration is where execution policy belongs because it cannot be forgotten there.