Skip Headers

# Join Reading and Object-Level Read Queries

Previous

Next

Join reading is a query optimization feature that allows a single query for a class to return the data to build the instances of that class and its related objects. Use this feature to improve query performance by reducing database access. By default, relationships are not join-read: each relationship is fetched separately when accessed if you are using indirection (see "Indirection"), or as a separate database query if you are not using indirection.

You can use join reading with `ReadObjectQuery` and `ReadAllObjectQuery` to join only one-to-one or one-to-many mapped relationships. Join reading is not currently supported for any other relationship mappings.

Join reading can specify multiple and nested relationships to be joined. Nested joins are expressed through using expressions (see "Expressions for Joining and Complex Relationships").

Outer joins can also be used with join reading through using the expression outer join API. If an outer join is not used, objects with missing one-to-one relationships or empty one-to-many relationships will be filtered from the result set.

You can use join reading between relationships to the same class, or to concrete or leaf inherited classes, but not to root or branch inherited classes that have multiple tables. For more information about inheritance, see "Understanding Descriptors and Inheritance".

Note: TopLink does not support joining to a class that takes multiple SQL calls to read. For example, joining to a superclass (potentially).

You can use join reading with custom SQL or stored procedures, but the query must ensure that all of the required data to build all of the join-read objects is returned. If the result set includes the same tables or fields, they must be returned in the same table order as TopLink would have generated.

For more information, see "Using Join Reading".