A Hibernate entity marks a business key such as a book's ISBN with @NaturalId and code looks rows up with session.bySimpleNaturalId(Book.class).load(isbn). What does adding Hibernate's @NaturalIdCache annotation change, and what SQL runs with and without it?

## What a natural id is A *natural id* is the business key of a row: an ISBN for a book, a SKU for a product, a login for a user. The table still has a surrogate primary key (`id`), because Hibernate wants a stable, narrow identifier for associations and caching, but application code frequently knows the business key instead. `@NaturalId` on one or more fields declares that key to Hibernate and unlocks a dedicated lookup API: ```java Book b = session.bySimpleNaturalId(Book.class).load(isbn); // single-attribute Book b = session.byNaturalId(Book.class) .using("isbn", isbn).load(); // general form ``` (`bySimpleNaturalId` only exists when the entity has exactly one `@NaturalId` attribute; a composite natural id must use `byNaturalId(...).using(...)` for each part.) ## Why this beats an equivalent JPQL query `select b from Book b where b.isbn = :isbn` returns the same row, but it always goes to the database unless the query cache is on, and it never consults the entity cache. The natural-id API is deliberately shaped as *resolve then load*, so both halves can be served from caches, and it participates in the persistence context: a natural-id load can be satisfied entirely from the current session, and `getReference`-style deferred loading is available via `getReference()` instead of `load()`. ## The two-step resolution in detail **Step 1 — resolve.** Hibernate needs the primary key that corresponds to the natural key. - Session (L1) scope: every session keeps a natural-id resolution map, so repeated lookups within one session resolve for free, and entities loaded by any means register their natural-id mapping there. - Without `@NaturalIdCache`, a cold session must ask the database: `select id from book where isbn = ?`. Note this returns *only the identifier*. - With `@NaturalIdCache`, the mapping is stored in the second-level cache in a region of its own, whose default name is the entity name suffixed with `##NaturalId` (e.g. `com.acme.Book##NaturalId`). A hit there skips the resolution SQL. **Step 2 — load.** With the primary key in hand, Hibernate performs the ordinary entity load: persistence context → entity region (if the entity is annotated `@Cache`/`@Cacheable`) → `select ... from book where id = ?`. This is why the region layout matters: **natural-id regions hold only identifiers, exactly like collection regions hold only element ids**. Entity state is never duplicated into them. The practical corollary is the same as for collections: `@NaturalIdCache` without entity caching buys you one query instead of two, not zero. ``` @NaturalIdCache only : select ... from book where id = ? @Cache only : select id from book where isbn = ? (then cache hit) both, warm : no SQL neither, cold session : two selects ``` ## Mutability and staleness By default `@NaturalId` fields are treated as immutable. Change one on a managed entity and Hibernate refuses at flush time with an error along the lines of *"An immutable natural identifier of entity com.acme.Book was altered"*. That is a feature: an immutable key means a cached mapping can never silently rot. If the key genuinely changes — a user renaming their login — declare `@NaturalId(mutable = true)`. Hibernate then tracks the previous value and, at flush, removes the outdated `oldValue -> id` entry from the natural-id region and inserts the new one. The cost is extra bookkeeping per update, so only mark keys mutable when they really are. As with any second-level region, statements that bypass the persistence context (bulk JPQL update/delete, native SQL, or another application writing the same table) leave the mapping stale; those need explicit eviction via `sessionFactory.getCache().evictNaturalIdData(Book.class)`. ## Consistency of the cached mapping A natural-id mapping is invalidated precisely, by entity change, rather than by a coarse timestamp. This is the key advantage over caching the equivalent lookup query: a query-result entry is validated against an update-timestamps region, so any write to the `book` table can invalidate every cached query over books, while a natural-id entry survives unrelated writes and is removed only when *that* entity's natural id changes or the entity is deleted. ## Practical guidance - Use `@NaturalId` wherever a stable business key exists — the API is clearer than a hand-written query and it is the only lookup path that can be answered from the session. - Add `@NaturalIdCache` when lookups by that key are hot and the entity is read-mostly, and pair it with `@Cache` on the entity so both halves are covered. - Batch form: `byMultipleNaturalId(Book.class).multiLoad(isbn1, isbn2, ...)` resolves several keys in one round trip, and it consults the same caches. - Enforce the natural id with a unique constraint in the schema; Hibernate does not add one automatically for you, and a duplicate business key breaks the resolution's one-row assumption.