Java Persistence API (JPA) Extensions Reference for EclipseLink, Release 2.5
  Go To Table Of Contents


Use @FetchGroup to load a group of attributes on demand, as needed.

This avoids wasteful practice of loading all data of the object's attributes, if which the user is interested in only partial of them. However, it also means that the data for an attribute might not loaded from the underlying data source until an explicit access call for the attribute first occurs.

Annotation Elements

Table 2-22 describes this annotation's elements.

Table 2-22 @FetchGroup Annotation Elements

Annotation Element Description Default

FetchAttribute[] attributes

(Required) The list of attributes to fetch.


java.lang.String name

(Required) The fetch group name.


boolean load

(Optional) Indicates whether all relationship attributes specified in the fetch group should be loaded.



You should perform a careful use case analysis when using @FetchGroup; any gains realized from the deferred loading could be offset by the extra round-trip.

EclipseLink supports fetch groups at two levels:

You can use fetch groups only when using weaving or when individual classes that define them explicitly implement the org.eclipse.persistence.queries.FetchGroupTracker interface.

When using a fetch group, you can define a subset of an object's attributes and associate the fetch group with a query. When you execute the query, EclipseLink retrieves only the attributes in the fetch group. EclipseLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a get method on any one of the excluded attributes.

You can define more than one fetch group for a class. You can optionally designate at most one such fetch group as the default fetch group. If you execute a query without specifying a fetch group, EclipseLink will use the default fetch group, unless you configure the query otherwise.

Before using fetch groups, we recommend that you perform a careful analysis of system use. In many cases, the extra queries required to load attributes not in the fetch group could well offset the gain from the partial attribute loading.


Example 2-44 show how to use this annotation.

Example 2-44 Using @FetchGroup Annotation

@FetchGroup(name="names", attributes={

Example 2-44 show how to use this feature in the eclipselink-orm.xml file.

Example 2-45 Using <fetch-group> XML

<entity class="model.Employee">
    <secondary-table name="SALARY" />
    <fetch-group name="names">
        <attribute name="firstName" />
        <attribute name="lastName" />

You can also use a named fetch group with a query, as shown in Example 2-46.

Example 2-46 Using a Named Fetch Group on a Query

TypedQuery query = em.createQuery("SELECT e FROM Employee e", Employee.class);
query.setHint(QueryHints.FETCH_GROUP_NAME, "names");

See Also

For more information, see: