Skip Headers

# Named Queries

Previous

Next

When you use a session query method like `readAllObjects` (see "Session Queries"), TopLink creates a corresponding `ReadAllQuery`, which builds other objects it needs to perform its task. When TopLink finishes execution of the `readAllObjects` method, these objects are discarded. Each time you call this session method, TopLink creates these related objects again, uses them once, and then discards them.

Alternatively, you can create a `DatabaseQuery` (see "Database Queries") and store it by name at the descriptor- (see "Configuring Named Queries at the Descriptor Level") or session-level (see "Configuring Named Queries at the Session Level").

TopLink prepares a named query once, and it (and all its associated supporting objects) can be efficiently reused thereafter making a named query well suited for frequently executed operations.

Using the `Session` API (see "Using Named Queries"), you can execute these queries by name, passing in any required arguments.

WARNING: Allowing an unverified SQL string to be passed into methods (for example: `readAllObjects(Class class, String sql)` method) makes your application vulnerable to SQL injection attacks.

When to Use Named Queries

For a reasonably complex query that you execute frequently, you should consider making the query a named query.

If a query is global to a project, configure the named query at the session level ("Configuring Named Queries at the Session Level").

If a query is global to a `Class` or you want to configure CMP finders, configure the named query at the descriptor level (see "Configuring Named Queries at the Descriptor Level"). For more information about descriptor level query configuration, see "Descriptor Query Manager Queries".

For a very complex query, you can delegate query execution to your own static method using a special form of a named query called a redirect query. For more information about redirect queries, see "Redirect Queries").

When Not to Use Named Queries

Rarely used queries may be more efficient when built on an as-needed basis. If you seldom use a given query, it may not be worthwhile to build and store that query when you invoke a session.