Entity Graph Basics

You can create entity graphs statically by using annotations or a deployment descriptor, or dynamically by using standard interfaces.

You can use an entity graph with the EntityManager.find method or as part of a JPQL or Criteria API query by specifying the entity graph as a hint to the operation or query.

Entity graphs have attributes that correspond to the fields that will be eagerly fetched during a find or query operation. The primary key and version fields of the entity class are always fetched and do not need to be explicitly added to an entity graph.

The Default Entity Graph

By default, all fields in an entity are fetched lazily unless the fetch attribute of the entity metadata is set to javax.persistence.FetchType.EAGER. The default entity graph consists of all the fields of an entity whose fields are set to be eagerly fetched.

For example, the following EmailMessage entity specifies that some fields will be fetched eagerly:

@Entity
public class EmailMessage implements Serializable {
    @Id
    String messageId;
    @Basic(fetch=EAGER)
    String subject;
    String body;
    @Basic(fetch=EAGER)
    String sender;
    @OneToMany(mappedBy="message", fetch=LAZY)
    Set<EmailAttachment> attachments;
    ...
}

The default entity graph for this entity would contain the messageId, subject, and sender fields, but not the body or attachments fields.

Using Entity Graphs in Persistence Operations

Entity graphs are used by creating an instance of the javax.persistence.EntityGraph interface by calling either EntityManager.getEntityGraph for named entity graphs or EntityManager.createEntityGraph for creating dynamic entity graphs.

A named entity graph is an entity graph specified by the @NamedEntityGraph annotation applied to entity classes, or the named-entity-graph element in the application’s deployment descriptors. Named entity graphs defined within the deployment descriptor override any annotation-based entity graphs with the same name.

The created entity graph can be either a fetch graph or a load graph.

The following topics are addressed here:

Fetch Graphs
Load Graphs

Fetch Graphs

To specify a fetch graph, set the javax.persistence.fetchgraph property when you execute an EntityManager.find or query operation. A fetch graph consists of only the fields explicitly specified in the EntityGraph instance, and ignores the default entity graph settings.

In the following example, the default entity graph is ignored, and only the body field is included in the dynamically created fetch graph:

EntityGraph<EmailMessage> eg = em.createEntityGraph(EmailMessage.class);
eg.addAttributeNodes("body");
...
Properties props = new Properties();
props.put("javax.persistence.fetchgraph", eg);
EmailMessage message = em.find(EmailMessage.class, id, props);

Load Graphs

To specify a load graph, set the javax.persistence.loadgraph property when you execute an EntityManager.find or query operation. A load graph consists of the fields explicitly specified in the EntityGraph instance plus any fields in the default entity graph.

In the following example, the dynamically created load graph contains all the fields in the default entity graph plus the body field:

EntityGraph<EmailMessage> eg = em.createEntityGraph(EmailMessage.class);
eg.addAttributeNodes("body");
...
Properties props = new Properties();
props.put("javax.persistence.loadgraph", eg);
EmailMessage message = em.find(EmailMessage.class, id, props);