JPA Entity Graphs

One of the latest features in JPA 2.1 is the ability to specify fetch plans using Entity Graphs. This is useful since it allows you to customize the data that is retrieved with a query or find operation. When working with mid to large size applications is common to display data from the same entity in different and many ways. In other cases, you just want to select a smallest set of information to optimize the performance of your application.

You don’t have many mechanisms to control what is loaded or not in a JPA Entity. You could use EAGER / LAZY fetching, but these definitions are pretty much static. You were unable to change their behaviour when retrieving data, meaning that you were stuck with what was defined in the entity. Changing these in mid development is a nightmare, since it can cause queries to behave unexpectedly. Another way to control loading is to write specific JPQL queries. You usually end up with very similar queries and the following methods: findEntityWithX, findEntityWithY, findEntityWithXandY, and so on.

Example

(Probably the relationships should be N to N, but lets keep it simple).

And the Movie Entity has the following definition:

Movie.java

Java

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

@Entity

@Table(name="MOVIE_ENTITY_GRAPH")

@NamedQueries({

@NamedQuery(name="Movie.findAll",query="SELECT m FROM Movie m")

})

@NamedEntityGraphs({

@NamedEntityGraph(

name="movieWithActors",

attributeNodes={

@NamedAttributeNode("movieActors")

}

),

@NamedEntityGraph(

name="movieWithActorsAndAwards",

attributeNodes={

@NamedAttributeNode(value="movieActors",subgraph="movieActorsGraph")

},

subgraphs={

@NamedSubgraph(

name="movieActorsGraph",

attributeNodes={

@NamedAttributeNode("movieActorAwards")

}

)

}

)

})

publicclassMovieimplementsSerializable{

@Id

privateIntegerid;

@NotNull

@Size(max=50)

privateStringname;

@OneToMany

@JoinColumn(name="ID")

privateSet<MovieActor>movieActors;

@OneToMany(fetch=FetchType.EAGER)

@JoinColumn(name="ID")

privateSet<MovieDirector>movieDirectors;

@OneToMany

@JoinColumn(name="ID")

privateSet<MovieAward>movieAwards;

}

Looking closer to the entity, we can see that we have three 1 to N relationships and movieDirectors is set to be Eagerly loaded. The other relationships are set to the default Lazy loading strategy. If we want to change this behaviour, we can define different loading models by using the annotation @NamedEntityGraph. Just set a name to identify it and then use the @NamedAttributeNode to specify which attributes of the root entity that you want to load. For relationships you need to set a name to the subgraph and then use @NamedSubgraph. In detail:

Annotations

Entity Graph movieWithActors

Java

1

2

3

4

5

6

@NamedEntityGraph(

name="movieWithActors",

attributeNodes={

@NamedAttributeNode("movieActors")

}

)

This defines an Entity Graph with name movieWithActors and specifies that the relationship movieActors should be loaded.

Entity Graph movieWithActorsAndAwards

Java

1

2

3

4

5

6

7

8

9

10

11

12

13

14

@NamedEntityGraph(

name="movieWithActorsAndAwards",

attributeNodes={

@NamedAttributeNode(value="movieActors",subgraph="movieActorsGraph")

},

subgraphs={

@NamedSubgraph(

name="movieActorsGraph",

attributeNodes={

@NamedAttributeNode("movieActorAwards")

}

)

}

)

This defines an Entity Graph with name movieWithActorsAndAwards and specifies that the relationship movieActors should be loaded. Additionally, it also specifies that the relationship movieActors should load the movieActorAwards.

Note that we don’t specify the id attribute in the Entity Graph. This is because primary keys are always fetched regardless of what’s being specified. This is also true for version attributes.

Hints

To use the Entity Graphs defined in a query, you need to set them as an hint. You can use two hint properties and these also influences the way the data is loaded.

You can use javax.persistence.fetchgraph and this hint will treat all the specified attributes in the Entity Graph as FetchType.EAGER. Attributes that are not specified are treated as FetchType.LAZY.

The other property hint is javax.persistence.loadgraph. This will treat all the specified attributes in the Entity Graph as FetchType.EAGER. Attributes that are not specified are treated to their specified or default FetchType.

To simplify, and based on our example when applying the Entity Graph movieWithActors:

Default / Specified

javax.persistence.fetchgraph

javax.persistence.loadgraph

movieActors

LAZY

EAGER

EAGER

movieDirectors

EAGER

LAZY

EAGER

movieAwards

LAZY

LAZY

LAZY

In theory, this should be how the different relationships are fetched. In practice, it may not work this way, because the JPA 2.1 specification also states that the JPA provider can always fetch extra state beyond the one specified in the Entity Graph. This is because the provider can optimize which data to fetch and end up loading much more stuff. You need to check your provider behaviour. For instance Hibernate always fetch everything that is specified as EAGER even when using the javax.persistence.fetchgraph hint. Check the issue here.

Query

Performing the query is easy. You do it as you would normally do, but just call setHint on the Query object:

Hint Entity Graph

Java

1

2

3

4

5

6

7

8

@PersistenceContext

privateEntityManager entityManager;

publicList<Movie>listMovies(Stringhint,StringgraphName){

returnentityManager.createNamedQuery("Movie.findAll")

.setHint(hint,entityManager.getEntityGraph(graphName))

.getResultList();

}

To get the Entity Graph you want to use on your query, you need to call the getEntityGraph method on the EntityManager and pass the name. Then use the reference in the hint. Hint must be either javax.persistence.fetchgraph or javax.persistence.loadgraph.

Programmatic

Annotations may become verbose, especially if you have big graphs or many Entity Graphs. Instead of using annotations, you can programmatically define Entity Graphs. Let’s see how:

Start by adding a static meta model Entity Class:

Movie_.java

Java

1

2

3

4

5

6

7

8

@StaticMetamodel(Movie.class)

publicabstractclassMovie_{

publicstaticvolatileSingularAttribute<Movie,Integer>id;

publicstaticvolatileSetAttribute<Movie,MovieAward>movieAwards;

publicstaticvolatileSingularAttribute<Movie,String>name;

publicstaticvolatileSetAttribute<Movie,MovieActor>movieActors;

publicstaticvolatileSetAttribute<Movie,MovieDirector>movieDirectors;

}

This is not really needed, you can reference the attributes by their string names, but this will give you type safety.

Resources

Extra Note: currently there is a bug in EclipseLink / Glassfish that prevents javax.persistence.loadgraph hint from working properly. Check the issue here.

Conclusion

Entity Graphs filled a gap missing in the JPA specification. They are an extra mechanism that helps you to query for what you really need. They also help you to improve the performance of your application. But be smart when using them. There might be a better way.

Comments ( 30 )

Enity Graphs are great, but there is a lot of bugs in EclipseLink and Hibernate implementations. As far as I know it doesn’t work using different dialects / databases in Hibernate. We tried using it with Oracle and hibernate generates SQL queries with incorrect syntax. EclipseLink also have problems but I dont remember what exacly was wrong.

Yes, Entity Graphs are not bug free yet. Even with very simple examples, I just found two issues that I described in the post. Since there are multiple combinations of queries x databases, it’s natural that maybe some corner cases are having problems. The best thing it to report these problem to the implementations so they can fix them 🙂

I started using entity graphs but when I try to load a lazy collection JPA returns repeated result, I understand that this is because of the JOIN , but how can avoid it and tell JPA that only load the collection without repeat the owner entity ??.

Has anyone gotten an entity graph to work with a query with multi-valued named or positional parameters?

For example: SELECT o FROM Order o WHERE o.company IN :companies

This query works fine without an entity graph, but when I add an entity graph hint, Hibernate fails to bind the named parameter. If the query parameter is single-valued (ie. WHERE o.company = :company), it works. Positional parameters fail with a different exception.

In your programmatic example, why not add the associations “movieActor”, “movieAwards” and “movieDirector” as attribute nodes? Also in my case adding “movieActors” as a subgraph with the attribute node “movieActorAwards”, fetched the deeper association with Hibernate 4.3.7. Does this programmatic example fetches the “movieActorAwards” as it is?

I’ve could have used the attribute nodes indeed. I guess that I’ve used the subgraph so I could change the loading in that particular subgraph as well.

Regarding the fetch of the node “movieActorAwards”, it always depends on the setting. As it is, no relationship is fetched because “movieActorAwards” defaults to LAZY. You would need to specified it to be fetched as an attribute or graph.

great article and thanks to you. I think you should also include
“Hint providing a “fetchgraph” EntityGraph. Attributes explicitly specified as AttributeNodes are treated as FetchType.EAGER (via join fetch or subsequent select). Note: Currently, attributes that are not specified are treated as FetchType.LAZY or FetchType.EAGER depending on the attribute’s definition in metadata, rather than forcing FetchType.LAZY” on fetch graph and “Hint providing a “loadgraph” EntityGraph. Attributes explicitly specified as AttributeNodes are treated as FetchType.EAGER (via join fetch or subsequent select). Attributes that are not specified are treated as FetchType.LAZY or FetchType.EAGER depending on the attribute’s definition in metadata” on loadgraph hints because reading at your article I once thought attributes that are not included will be forced to be lazy on fetch hint regardless of its metadata defined.

Now the description of the fetch type hints is confusing; according to the JPA 2.1 Spec section 3.7.4:

javax.persistence.fetchgraph: “attributes that are not specified are treated as FetchType.LAZY”
javax.persistence.loadgraph: “attributes that are not specified are treated according to their specified or default FetchType”