14.2. Eager Fetching

14.2. Eager Fetching
Prev	Chapter 14. Performance Pack	Next

14.2.1. Configuring Eager Fetching
14.2.2. Eager Fetching Considerations

Eager fetching is the ability to efficiently load related objects along with the objects being queried. Typically, Kodo JDO has to make a trip to the database whenever a relation is loaded. If you perform a query that returns 100 Person objects, and then you have to retrieve the Address for each person, Kodo may make as many as 101 data store queries (the initial query, plus one for the address of each person returned). With eager fetching, Kodo can reduce this to a single query.

Eager fetching only affects relations in the fetch groups being loaded. In other words, relations that would not normally be loaded immediately when retrieving an object or accessing a field are not affected by eager fetching. In our example above, the address of each person would only be eagerly fetched if the query were configured to include the address field's fetch group (or if the address were in the default fetch group). This allows you to control exactly which fields are eagerly fetched.

Eager fetching has three modes:

none: No eager fetching is performed. Related objects are always loaded in a separate select statement.

single: In this mode, 1-1 relations in the configured fetch groups are eagerly fetched when selecting for objects. A left outer join (or inner join, if the 1-1 relations' field metadata sets the null-value attribute to exception) is used to select the relations' data along with the data for the target objects. This process works recursively, so that if Person has an Address, and Address has a TelephoneNumber, and the fetch groups are configured correctly, Kodo might issue a single select that joins across the tables for all three classes.

	Note
	Some databases may not support outer joins. Also, Kodo JDO can not use left outer joins if you have set the `kodo.jdbc.DBDictionary` configuration parameter's `JoinSyntax` to property `traditional`.

multiple: 1-1, 1-many, and many-many relations in the configured fetch groups are all eagerly fetched, along with fields holding collections of simple values.
1-1 relations are selected as described in the single mode description above. To-many relations and collection fields, on the other hand, are fetched using a separate select statement for each relation, batched together with the select statement for the target objects. The batched selects use the where conditions from the primary select, but add their own joins to reach the related data. Thus, if you perform a query that returns 100 Company objects, where each company has a list of Employee objects and Department objects, 3 queries will be made. The first will select the company objects, the second will select the employee objects for those companies, and the third will select the department objects for the same companies. Just as for 1-1 relations, this process can be recursively applied to the objects in the relations being eagerly fetched. If the Employee class had a list of Projects in one of the fetch groups being loaded, a single additional select would be batched that would load the projects of each employee of the matching companies.
Using an additional select to load each to-many relation avoids transferring more data than necessary from the database to the application. If outer joins were used instead of separate select statements, each to-many relation added to the configured fetch groups would cause the amount of data being transferred to rise dangerously, to the point that you could easily overwhelm the network.
When Kodo knows that it is selecting for a single object only, such as in calls to getObjectById, it never uses multiple mode, because the additional selects can be made lazily just as efficiently. This mode only increases efficiency over single mode when multiple objects are being loaded.

14.2.1. Configuring Eager Fetching

You can control Kodo's default eager fetch mode through the kodo.EagerFetchMode configuration property. Set this property to one of the mode names described in the previous section: none, single, multiple. If left unset, it defaults to multiple (assuming you have purchased the performance pack).

You can also override the default eager fetch mode on individual Kodo persistence managers, queries, and extents. All of these components give you access to their internal FetchConfiguration object for controlling object loading behavior. The runtime interfaces chapter of this manual details these interfaces, including the FetchConfiguration.

Example 14.2. Setting the Default Eager Fetch Mode

kodo.EagerFetchMode: single

Example 14.3. Setting the Eager Fetch Mode at Runtime

import kodo.runtime.*;

...

KodoQuery kq = (KodoQuery) pm.newQuery (Person.class, "address.state == \"TX\"");
kq.getFetchConfiguration ().setEagerFetchMode 
   (FetchConfiguration.EAGER_FETCH_SINGLE);
Collection results = (Collection) kq.execute ();

14.2.2. Eager Fetching Considerations

There are three important limitations of eager fetching that you should consider. First, when Kodo uses multiple selects to gather eager data under the multiple eager fetch mode, lazy result set support is turned off. Kodo will fully process each of the result sets immediately. Note that this applies only to result sets where secondary eager selects are made; if there are no to-many relations in the configured fetch groups that require separate selects, then lazy result set support will remain on, regardless of the eager fetch mode setting.

Second, eager fetching can be less efficient than standard fetching when circular relations are included in the configured fetch groups. For example, if type A has a relation to type B, and B has a relation back to A, and both relations are in the default fetch group or a configured fetch group, Kodo will be most efficient with eager fetching turned off.

Finally, when Kodo eager-fetches a 1-1 relation, any recursive eager fetching from that relation is in single mode. Kodo cannot eager-fetch a 1-1, and then recursively eager-fetch a to-many relation from that 1-1.