Skip Headers

# Configuring Fetch Groups

Previous

Next

By default, when you execute an object-level read query for a particular object class, TopLink returns all the persistent attributes mapped in the object's descriptor. With this single query, all the object's persistent attributes are defined, and calling their `get` methods returns the value directly from the object.

When you are interested in only some of the attributes of an object, it may be more efficient to return only a subset of the object's attributes using a fetch group.

Using a fetch group, you can define a subset of an object's attributes and associate the fetch group with either a `ReadObjectQuery` or `ReadAllQuery` query. When you execute the query, TopLink retrieves only the attributes in the fetch group. TopLink 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 either a `ReadObjectQuery` or `ReadAllQuery` query without specifying a fetch group, TopLink will use the default fetch group, unless you configure the query otherwise (see "Configuring Default Fetch Group Behavior").

Currently, you can use fetch groups only in CMP projects for EJB objects. For non-CMP classes, use partial object querying (see "Partial Object Queries").

Before using fetch groups, Oracle recommends 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. For more information about optimizing read performance, see "Read Optimization Examples".

Table: Descriptor Support for Fetch Group Configuration summarizes which descriptors support fetch group configuration.

Descriptor Support for Fetch Group Configuration

Descriptor | Using TopLink Workbench | Using Java
--- | --- | ---
Relational Descriptors |  |
Object-Relational Descriptors |  |
EIS Descriptors |  |
XML Descriptors |  |

This section describes how to create a fetch group, store it in a descriptor, and optionally designate a fetch group as the default fetch group for its descriptor reference class.

For more information, see the following:

- "Fetch Groups"

- "Fetch Groups and Object-Level Read Queries"

- "Configuring Default Fetch Group Behavior"