About Query Hints

JPA Cache Query Hints

The JPA query hints allow for queries or the find() operation to bypass, or refresh the shared cache. JPA cache query hints can be set on named or dynamic queries, or set in the properties map passed to the find() operation.

JPA 2.0 defines the following query hint properties to configure a queries interaction with the shared cache:

• jakarta.persistence.cache.retrieveMode

• jakarta.persistence.cache.storeMode

EclipseLink Extensions to Cache Query Hints

The EclipseLink cache query hints allow for queries or the find() operation to interact with the cache is the following ways:

• Bypass the cache check and force accessing the database, but still resolve with the cache.

• Refresh the cache from the database results.

• Bypass the cache and persistence unit and return detached objects.

• Bypass the persistence context and return read-only objects.

• Allow queries that use Id fields, and other fields to obtain cache hits.

• Query the cache first, and only access the database if the object is not found.

• Only query the cache, and avoid accessing the database.

• Conform a query with non-flushed changes in a persistence context.

Queries that access the cache have the following restrictions:

• Sub-selects are not supported.

• Certain database functions are not supported.

• Queries must return a single set of objects.

• Grouping is not supported.

• Uninstantiated lazy relationships may not be able to be queried.

All EclipseLink query hints are defined in the QueryHints class in the org.eclipse.persistence.config package. When you set a hint, you can set the value using the public static final field in the appropriate configuration class in org.eclipse.persistence.config package, including the following:

• HintValues

• CacheUsage

• PessimisticLock

• QueryType

You can specify EclipseLink query hints (JPA query extensions) either by using the @QueryHint annotation, by including the hints in the orm.xml or eclipselink-orm.xml files. or by using the setHint() method when executing a named or dynamic query (JPQL or Criteria).

Query settings and query hints that affect the generated SQL are not supported with SQL queries. Unsupported query hints include:

• batch

• history.as-of

• inheritance.outer-join

• sql.hint

• join-fetch—join-fetch is supported, but requires that the SQL selects all of the joined columns.

• fetch-group—fetch-group is supported, but requires that the SQL selects all of the fetched columns.

• pessimistic-lock—pessimistic-lock is supported, but requires that the SQL locks the result rows.

For descriptions of these extensions, see "EclipseLink Query Language" in Jakarta Persistence API (JPA) Extensions Reference for EclipseLink.