Package org.hibernate.annotations

Annotation Interface NamedQuery

@Target({TYPE,PACKAGE})
@Retention(RUNTIME)
@Repeatable(NamedQueries.class)
public @interface NamedQuery

Declares a named query written in HQL or JPQL.

Whereas NamedQuery allows settings to be specified using stringly-typed QueryHints, this annotation is typesafe.

Note that the members of this annotation correspond to hints enumerated by AvailableHints.

See Also:

• Query

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	name	The name of this query.
String	query	The text of the HQL query.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	cacheable	Whether the query results are cacheable.
@Remove CacheModeType	cacheMode	Deprecated. use cacheStoreMode() and cacheRetrieveMode() since CacheModeType is deprecated
String	cacheRegion	If the query results are cacheable, the name of the query cache region.
CacheRetrieveMode	cacheRetrieveMode	The cache retrieval mode for objects returned by this query.
CacheStoreMode	cacheStoreMode	The cache storage mode for objects returned by this query.
String	comment	A comment added to the generated SQL query.
int	fetchSize	The number of rows fetched by the JDBC driver per trip.
FlushModeType	flushMode	The flush mode for this query.
boolean	readOnly	Whether the results should be loaded in read-only mode.
int	timeout	The query timeout in seconds.

Element Details

name

String name

The name of this query. Must be unique within a persistence unit.

query

String query

The text of the HQL query.

flushMode

FlushModeType flushMode

The flush mode for this query.

See Also:

• CommonQueryContract.setFlushMode(jakarta.persistence.FlushModeType)
• HibernateHints.HINT_FLUSH_MODE

Default:

PERSISTENCE_CONTEXT

cacheable

boolean cacheable

Whether the query results are cacheable. Default is false, that is, not cacheable.

See Also:

• SelectionQuery.setCacheable(boolean)
• HibernateHints.HINT_CACHEABLE

Default:

false

cacheRegion

String cacheRegion

If the query results are cacheable, the name of the query cache region.

See Also:

• SelectionQuery.setCacheRegion(String)
• HibernateHints.HINT_CACHE_REGION

Default:

""

fetchSize

int fetchSize

The number of rows fetched by the JDBC driver per trip.

See Also:

• SelectionQuery.setFetchSize(int)
• HibernateHints.HINT_FETCH_SIZE

Default:

-1

timeout

int timeout

The query timeout in seconds. Default is no timeout.

See Also:

• CommonQueryContract.setTimeout(int)
• HibernateHints.HINT_TIMEOUT
• SpecHints.HINT_SPEC_QUERY_TIMEOUT

Default:

-1

comment

String comment

A comment added to the generated SQL query. Useful when engaging with DBA.

See Also:

• CommonQueryContract.setComment(String)
• HibernateHints.HINT_COMMENT

Default:

""

cacheStoreMode

CacheStoreMode cacheStoreMode

The cache storage mode for objects returned by this query.

See Also:

• Query.setCacheStoreMode(CacheStoreMode)
• SpecHints.HINT_SPEC_CACHE_STORE_MODE

Default:

USE

cacheRetrieveMode

CacheRetrieveMode cacheRetrieveMode

The cache retrieval mode for objects returned by this query.

See Also:

• Query.setCacheRetrieveMode(CacheRetrieveMode)
• SpecHints.HINT_SPEC_CACHE_RETRIEVE_MODE

Default:

USE

cacheMode

@Deprecated(since="6.2")
@Remove
@Remove CacheModeType cacheMode

Deprecated.

use cacheStoreMode() and cacheRetrieveMode() since CacheModeType is deprecated

The cache interaction mode for this query.

See Also:

• HibernateHints.HINT_CACHE_MODE

Default:

NORMAL

readOnly

boolean readOnly

Whether the results should be loaded in read-only mode. Default is false.

See Also:

• SelectionQuery.setReadOnly(boolean)
• HibernateHints.HINT_READ_ONLY

Default:

false