What is a JPA entity graph, and how do you define and apply one — both declaratively with @NamedEntityGraph and programmatically with EntityManager.createEntityGraph?

## Why entity graphs exist Mappings declare a *default* fetch plan (`LAZY` or `EAGER`) that applies everywhere. Real applications need different plans per use case: a list screen wants the root only, a detail screen wants two levels of children, an export wants nearly everything. `JOIN FETCH` solves that but bakes the plan into the query string — so you end up with three near-identical JPQL statements differing only in their fetch clauses. An **entity graph** separates *what to load* from *what to select*. It is a first-class object describing a subtree of attributes, attachable to any query or `find()`. ## Declaring a named graph ```java @Entity @NamedEntityGraph( name = "Order.withItemsAndCustomer", attributeNodes = { @NamedAttributeNode("customer"), @NamedAttributeNode(value = "items", subgraph = "itemDetail") }, subgraphs = @NamedSubgraph( name = "itemDetail", attributeNodes = @NamedAttributeNode("product")) ) public class Order { ... } ``` `attributeNodes` are the attributes to fetch; a `subgraph` continues the plan into the child entity, which is how you express two- and three-level graphs. Retrieve it with `em.createEntityGraph("Order.withItemsAndCustomer")` — note the string overload returns the named graph, while the `Class` overload creates an empty one. ## Building one programmatically ```java EntityGraph<Order> g = em.createEntityGraph(Order.class); g.addAttributeNode("customer"); Subgraph<OrderItem> items = g.addSubgraph("items"); items.addAttributeNode("product"); ``` The programmatic form matters when the plan depends on runtime input — for example an API where the caller passes `?expand=items,customer` and you translate each token into an attribute node. It also avoids scattering annotations across entities for one-off needs. Attribute names are strings, so they are not refactor-safe. The JPA static metamodel (`Order_.items`) gives typed overloads in `addAttributeNode(Attribute)` / `addSubgraph(Attribute)` and is worth using in a codebase that generates the metamodel. ## Applying a graph Two hint names, both in the `jakarta.persistence.` namespace (`javax.persistence.` before Jakarta EE 9): - `jakarta.persistence.fetchgraph` — a **fetch graph**. Attributes named in the graph are treated as `EAGER`; **every attribute not named is treated as LAZY**, regardless of its mapping. - `jakarta.persistence.loadgraph` — a **load graph**. Attributes named are `EAGER`; attributes not named keep their **mapped** fetch type, so mapped-EAGER associations still load. Apply to a query: ```java em.createQuery("select o from Order o where o.status = :s", Order.class) .setParameter("s", status) .setHint("jakarta.persistence.loadgraph", g) .getResultList(); ``` Or to a lookup by id: ```java em.find(Order.class, id, Map.of("jakarta.persistence.fetchgraph", g)); ``` The `find()` case is the one `JOIN FETCH` cannot cover at all — there is no query to attach a fetch clause to. ## What Hibernate actually emits A graph is a *requirement*, not a join instruction. Hibernate decides how to satisfy it: typically an outer join for to-one and to-many attributes in one statement, but it may also use separate selects (particularly for multiple collections, avoiding the cartesian blow-up that a hand-written double `JOIN FETCH` would hit). You give up control of join type and ordering; in exchange you cannot write an inner-join-drops-rows bug. A hard caveat: a graph applied to a JPQL query that already contains its own `JOIN FETCH` for the same association is redundant at best and confusing at worst. Pick one mechanism per association per query. One more limit worth knowing: `@Basic` attributes can appear in a graph, but making a basic column lazy requires bytecode enhancement — without it, a fetch graph will not actually stop a scalar column from loading. Graphs are reliable for **associations**, best-effort for basics. ## Choosing between graphs and JOIN FETCH Reach for **JOIN FETCH** when the fetch is intrinsic to one query, when you need `LEFT` explicitly, or when the query is already bespoke. Reach for an **entity graph** when the same shape is needed from several call sites, when the plan is chosen at runtime, or when you need a plan on `find()`. Neither replaces batch fetching for the case where you genuinely want many small selects rather than one wide join.