The JPA Entity Graph allows you to override the default fetch plan.
Default Fetch Plan
As I explained in this article, every entity has a default fetch plan that’s defined during entity mapping and instructs Hibernate how to fetch entity associations.
By default, @ManyToOne and @OneToOne associations use the FetchTyp.EAGER strategy, which is a terrible choice from a performance perspective. So, for this reason, it’s good practice to set all @ManyToOne and @OneToOne associations to use the FetchType.LAZY strategy, like in the following example:
@Entity(name = "PostComment")
@Table(name = "post_comment")
public class PostComment {
@Id
private Long id;
@ManyToOne(fetch = FetchType.LAZY)
private Post post;
private String review;
//Getters and setters omitted for brevity
}
When fetching the PostComment entity using the find method:
PostComment comment = entityManager.find(PostComment.class, 1L);
Hibernate executes the following SQL query:
SELECT pc.id AS id1_1_0_,
pc.post_id AS post_id3_1_0_,
pc.review AS review2_1_0_
FROM post_comment pc
WHERE pc.id = 1
The post association is fetched as a Proxy that has only the id set by the post_id Foreign Key column that was loaded by the aforementioned SQL query.
When accessing any non-id property of the post Proxy:
LOGGER.info("The comment post title is '{}'", comment.getPost().getTitle());
A secondary SQL query is executed that fetched the Post entity on-demand:
SELECT p.id AS id1_0_0_,
p.title AS title2_0_0_
FROM post p
WHERE p.id = 1
-- The comment post title is 'High-Performance Java Persistence, part 1'
Overriding the default Fetch Plan
If we want to override the default fetch plan and fetch the post association eagerly at query execution time, we can use a JPQL query that instructs Hibernate to fetch the lazy association using the FETCH JOIN clause:
PostComment comment = entityManager.createQuery("""
select pc
from PostComment pc
left join fetch pc.post
where pc.id = :id
""", PostComment.class)
.setParameter("id", 1L)
.getSingleResult();
LOGGER.info("The comment post title is '{}'", comment.getPost().getTitle());
Then, the default fetch plan is going to be overridden, and the post association will be fetched eagerly:
SELECT pc.id AS id1_1_0_,
p.id AS id1_0_1_,
pc.post_id AS post_id3_1_0_,
pc.review AS review2_1_0_,
p.title AS title2_0_1_
FROM post_comment pc
LEFT JOIN post p ON pc.post_id = p.id
WHERE pc.id = 1
Declarative JPA Entity Graph
The default fetch plan can also be overridden using a JPA Entity Graph. For instance, we could define a specific fetch plan using the following JPA @EntityGraph annotation:
@Entity(name = "PostComment")
@Table(name = "post_comment")
@NamedEntityGraph(
name = "PostComment.post",
attributeNodes = @NamedAttributeNode("post")
)
public class PostComment {
//Code omitted for brevity
}
With the PostComment.post Entity Graph in place, we can now load the PostComment entity along with its associated post entity, like this:
PostComment comment = entityManager.find(
PostComment.class,
1L,
Collections.singletonMap(
"javax.persistence.loadgraph",
entityManager.getEntityGraph("PostComment.post")
)
);
And, when executing the above find method, Hibernate generates the following SQL SELECT query:
SELECT pc.id AS id1_1_0_,
pc.post_id AS post_id3_1_0_,
pc.review AS review2_1_0_,
p.id AS id1_0_1_,
p.title AS title2_0_1_
FROM post_comment pc
LEFT OUTER JOIN post p ON pc.post_id = p.id
WHERE pc.id = 1
If you're using Spring, then you can reference the JPA Entity Graph in a Repository method using the @EntityGraph annotation:
@Repository
public interface PostCommentRepository
extends CrudRepository<PostComment, Long> {
@EntityGraph(
value = "PostComment.post",
type = EntityGraphType.LOAD
)
PostComment findById(Long id);
}
Programmatic JPA Entity Graph
If you don't like annotations, then you can also build the JPA Entity Graph programmatically, using the createEntityGraph method of the JPA EntityManager, as illustrated by the following example:
EntityGraph<PostComment> postCommentGraph = entityManager
.createEntityGraph(PostComment.class);
postCommentGraph.addAttributeNodes("post");
PostComment comment = entityManager.find(
PostComment.class,
1L,
Collections.singletonMap(
"javax.persistence.loadgraph",
postCommentGraph
)
);
