Interface Query<T>

Type Parameters:

T - The result type for selection queries or the target type for mutation queries.

All Superinterfaces:

CommonQueryContract, Query

All Known Subinterfaces:

MutationQueryImplementor<T>, NativeQuery<T>, NativeQueryImplementor<R>, ProcedureCallImplementor<R>, QueryImplementor<T>, SelectionQuery<R>, SelectionQueryImplementor<R>

@Incubating
public interface Query<T>
extends CommonQueryContract

Within the context of an active session, an instance of this type represents an executable query, either:

• a Query written in HQL or native SQL,
• a named Query written in HQL or native SQL, or
• a criteria query.

The subtype NativeQuery represents a Query written in native SQL.

This type simply mixes the TypedQuery interface defined by JPA with SelectionQuery and MutationQuery. Unfortunately, JPA does not distinguish between selection queries and mutation queries, so we lose that distinction here. However, every Query may logically be classified as one or the other.

A Query may be obtained from the Session by calling:

• SharedSessionContract.createQuery(String, Class), passing the HQL as a string,
• SharedSessionContract.createQuery(jakarta.persistence.criteria.CriteriaQuery), passing a criteria object, or
• SharedSessionContract.createNamedQuery(String, Class) passing the name of a Query defined using NamedQuery or NamedNativeQuery.

A Query controls how a Query is executed, and allows arguments to be bound to its parameters.

• Selection queries are usually executed using getResultList() or getSingleResult().
• The methods setMaxResults(int) and setFirstResult(int) control limits and pagination.
• The various overloads of setParameter(String, Object) and setParameter(int, Object) allow arguments to be bound to named and ordinal parameters defined by the query.

Note that this interface offers no real advantages over SelectionQuery except for compatibility with the JPA-defined TypedQuery interface.

See Also:

• SelectionQuery
• MutationQuery
• ProcedureCall
• Query

Method Summary

Modifier and Type	Method	Description
Query<T>	addQueryHint(String hint)	Add a database query hint to the SQL query.
SelectionQuery<T>	asSelectionQuery()	Casts this query as a SelectionQuery.
MutationQuery	asStatement()	Covariant override of Query.asStatement().
int	executeUpdate()	Deprecated. Use MutationQuery instead for queries which mutate data.
CacheMode	getCacheMode()	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as caching is only relevant for selection queries
String	getCacheRegion()	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as caching is only relevant for selection queries
Integer	getFetchSize()	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as fetch size is only relevant for selection queries
default FlushModeType	getFlushMode()	Deprecated.
LockMode	getHibernateLockMode()	Deprecated. Use SelectionQuery instead as locking are only relevant for queries which return results.
Timeout	getLockTimeout()	Deprecated. Use SelectionQuery instead as locking is only relevant for queries which return results.
QueryOptions	getQueryOptions()	Deprecated, for removal: This API element is subject to removal in a future version. The various Query subtypes already expose all relevant options; plus exposing QueryOptions is layer-breaking as it is an SPI contract exposed on an API.
String	getQueryString()	The Query as a string, or null in the case of a criteria query.
default List<T>	getResultList()	Deprecated. Use SelectionQuery instead for queries which return results.
default Stream<T>	getResultStream()	Deprecated. Use SelectionQuery instead for queries which return results.
T	getSingleResult()	Deprecated. Use SelectionQuery instead for queries which return results.
boolean	isCacheable()	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as caching is only relevant for selection queries
boolean	isQueryPlanCacheable()	Whether the execution plan for this Query is cached.
boolean	isReadOnly()	Should entities and proxies loaded by this Query be put in read-only mode? If the read-only/modifiable setting was not initialized, then the default read-only/modifiable setting for the persistence context i s returned instead.
List<T>	list()	Deprecated. Use SelectionQuery instead for queries which return results.
<R> SelectionQuery<R>	ofType(Class<R> type)	Covariant override of Query.ofType(Class).
ScrollableResults<T>	scroll()	Deprecated. Use SelectionQuery instead for queries which return results.
ScrollableResults<T>	scroll(ScrollMode scrollMode)	Deprecated. Use SelectionQuery instead for queries which return results.
Query<T>	setCacheable(boolean cacheable)	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as caching is only relevant for selection queries
Query<T>	setCacheMode(CacheMode cacheMode)	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as caching is only relevant for selection queries
Query<T>	setCacheRegion(String cacheRegion)	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as caching is only relevant for selection queries
Query<T>	setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)	Deprecated. Use SelectionQuery instead as second-level cache interaction is only relevant for queries which return results.
Query<T>	setCacheStoreMode(CacheStoreMode cacheStoreMode)	Deprecated. Use SelectionQuery instead as second-level cache interaction is only relevant for queries which return results.
Query<T>	setComment(String comment)	Set the comment for this query.
<P> Query<T>	setConvertedParameter(int position, P value, Class<? extends AttributeConverter<P,?>> converter)
<P> Query<T>	setConvertedParameter(String name, P value, Class<? extends AttributeConverter<P,?>> converter)
Query<T>	setFetchSize(int fetchSize)	Deprecated, for removal: This API element is subject to removal in a future version. Use SelectionQuery instead as fetch size is only relevant for selection queries
Query<T>	setFirstResult(int startPosition)	Deprecated. Use SelectionQuery instead as applying result limits is only relevant for queries which return results.
default Query<T>	setFlushMode(FlushModeType flushMode)	Deprecated. Use setQueryFlushMode(QueryFlushMode) instead.
Query<T>	setFollowOnLockingStrategy(Locking.FollowOn strategy)	Deprecated. Use SelectionQuery instead as locking is only relevant for queries which return results.
Query<T>	setFollowOnStrategy(Locking.FollowOn strategy)	Deprecated. Use SelectionQuery instead as locking is only relevant for queries which return results.
Query<T>	setHibernateLockMode(LockMode lockMode)	Deprecated. Use SelectionQuery instead as locking are only relevant for queries which return results.
Query<T>	setHint(String hintName, Object value)	Set a hint.
Query<T>	setLockMode(LockModeType lockMode)	Deprecated. Use SelectionQuery instead as locking are only relevant for queries which return results.
Query<T>	setLockScope(PessimisticLockScope lockScope)	Deprecated. Use SelectionQuery instead as locking is only relevant for queries which return results.
Query<T>	setLockTimeout(Timeout lockTimeout)	Deprecated. Use SelectionQuery instead as locking is only relevant for queries which return results.
Query<T>	setMaxResults(int maxResults)	Deprecated. Use SelectionQuery instead as applying result limits is only relevant for queries which return results.
Query<T>	setParameter(int parameter, Object argument)	Bind the given argument to an ordinal query parameter.
Query<T>	setParameter(int parameter, Instant argument, TemporalType temporalType)	Deprecated.
Query<T>	setParameter(int parameter, Calendar argument, TemporalType temporalType)	Deprecated.
Query<T>	setParameter(int parameter, Date argument, TemporalType temporalType)	Deprecated.
<P> Query<T>	setParameter(int parameter, P argument, Type<P> type)	Bind the given argument to an ordinal query parameter using the given Type.
<P> Query<T>	setParameter(int parameter, P argument, Class<P> type)	Bind the given argument to an ordinal query parameter using the given Class reference to attempt to infer the Type.
Query<T>	setParameter(Parameter<Calendar> parameter, Calendar argument, TemporalType temporalType)	Deprecated.
Query<T>	setParameter(Parameter<Date> parameter, Date argument, TemporalType temporalType)	Deprecated.
<P> Query<T>	setParameter(Parameter<P> parameter, P argument)
Query<T>	setParameter(String parameter, Object argument)	Bind the given argument to a named query parameter.
Query<T>	setParameter(String parameter, Instant argument, TemporalType temporalType)	Deprecated.
Query<T>	setParameter(String parameter, Calendar argument, TemporalType temporalType)	Deprecated.
Query<T>	setParameter(String parameter, Date argument, TemporalType temporalType)	Deprecated.
<P> Query<T>	setParameter(String parameter, P argument, Type<P> type)	Bind the given argument to a named query parameter using the given Type.
<P> Query<T>	setParameter(String parameter, P argument, Class<P> type)	Bind the given argument to a named query parameter using the given Class reference to attempt to infer the Type.
<P> Query<T>	setParameter(QueryParameter<P> parameter, P argument)	Bind an argument to the query parameter represented by the given QueryParameter.
<P> Query<T>	setParameter(QueryParameter<P> parameter, P argument, Type<P> type)	Bind an argument to the query parameter represented by the given QueryParameter, using the given Type.
<P> Query<T>	setParameter(QueryParameter<P> parameter, P argument, Class<P> type)	Bind an argument to the query parameter represented by the given QueryParameter, using the given Class reference to attempt to infer the Type to use.
Query<T>	setParameterList(int parameter, Object[] arguments)	Bind multiple arguments to an ordinal query parameter.
Query<T>	setParameterList(int parameter, Collection arguments)	Bind multiple arguments to an ordinal query parameter.
<P> Query<T>	setParameterList(int parameter, Collection<? extends P> arguments, Type<P> type)	Bind multiple arguments to an ordinal query parameter using the given Type.
<P> Query<T>	setParameterList(int parameter, Collection<? extends P> arguments, Class<P> javaType)	Bind multiple arguments to an ordinal query parameter using the given Class reference to attempt to infer the Type.
<P> Query<T>	setParameterList(int parameter, P[] arguments, Type<P> type)	Bind multiple arguments to an ordinal query parameter using the given Type.
<P> Query<T>	setParameterList(int parameter, P[] arguments, Class<P> javaType)	Bind multiple arguments to an ordinal query parameter using the given Class reference to attempt to infer the Type.
Query<T>	setParameterList(String parameter, Object[] values)	Bind multiple arguments to a named query parameter.
Query<T>	setParameterList(String parameter, Collection arguments)	Bind multiple arguments to a named query parameter.
<P> Query<T>	setParameterList(String parameter, Collection<? extends P> arguments, Type<P> type)	Bind multiple arguments to a named query parameter using the given Type.
<P> Query<T>	setParameterList(String parameter, Collection<? extends P> arguments, Class<P> javaType)	Bind multiple arguments to a named query parameter using the given Class reference to attempt to infer the Type If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameterList(String, Collection).
<P> Query<T>	setParameterList(String parameter, P[] arguments, Type<P> type)	Bind multiple arguments to a named query parameter using the given Type.
<P> Query<T>	setParameterList(String parameter, P[] arguments, Class<P> javaType)	Bind multiple arguments to a named query parameter using the given Class reference to attempt to determine the Type to use.
<P> Query<T>	setParameterList(QueryParameter<P> parameter, Collection<? extends P> arguments)	Bind multiple arguments to the query parameter represented by the given QueryParameter.
<P> Query<T>	setParameterList(QueryParameter<P> parameter, Collection<? extends P> arguments, Type<P> type)	Bind multiple arguments to the query parameter represented by the given QueryParameter, using the given Type.
<P> Query<T>	setParameterList(QueryParameter<P> parameter, Collection<? extends P> arguments, Class<P> javaType)	Bind multiple arguments to the query parameter represented by the given QueryParameter using the given Class reference to attempt to infer the Type to use.
<P> Query<T>	setParameterList(QueryParameter<P> parameter, P[] arguments)	Bind multiple arguments to the query parameter represented by the given QueryParameter.
<P> Query<T>	setParameterList(QueryParameter<P> parameter, P[] arguments, Type<P> type)	Bind multiple arguments to the query parameter represented by the given QueryParameter, using the given the Type.
<P> Query<T>	setParameterList(QueryParameter<P> parameter, P[] arguments, Class<P> javaType)	Bind multiple arguments to the query parameter represented by the given QueryParameter using the given Class reference to attempt to infer the Type to use.
Query<T>	setProperties(Object bean)	Bind the property values of the given bean to named parameters of the query, matching property names with parameter names and mapping property types to Hibernate types using heuristics.
Query<T>	setProperties(Map bean)	Bind the values of the given Map to named parameters of the query, matching key names with parameter names and mapping value types to Hibernate types using heuristics.
Query	setQueryFlushMode(QueryFlushMode queryFlushMode)	Set the QueryFlushMode to use for this query.
Query<T>	setQueryPlanCacheable(boolean queryPlanCacheable)	Enable/disable Query plan caching for this query, if available.
Query<T>	setReadOnly(boolean readOnly)	Set the read-only/modifiable mode for entities and proxies loaded by this Query.
Query<T>	setResultListTransformer(ResultListTransformer<T> transformer)	Set a ResultListTransformer.
Query<T>	setTimeout(int timeout)	Apply a timeout to the corresponding database query.
Query<T>	setTimeout(Timeout timeout)	Apply a timeout to the corresponding database query.
Query<T>	setTimeout(Integer timeout)	Apply a timeout to the corresponding database query.
<X> Query<X>	setTupleTransformer(TupleTransformer<X> transformer)	Set a TupleTransformer.
default Stream<T>	stream()	Deprecated. Use SelectionQuery instead for queries which return results.
T	uniqueResult()	Deprecated. Use SelectionQuery instead for queries which return results.
Optional<T>	uniqueResultOptional()	Deprecated. Use SelectionQuery instead for queries which return results.
<R> SelectionQuery<R>	withEntityGraph(EntityGraph<R> entityGraph)	Covariant override of Query.withEntityGraph(EntityGraph).

Methods inherited from interface CommonQueryContract

asMutationQuery, asSelectionQuery, asSelectionQuery, asSelectionQuery, getComment, getEffectiveFlushMode, getParameterMetadata, getQueryFlushMode, getSession, getTimeout

Methods inherited from interface Query

getCacheRetrieveMode, getCacheStoreMode, getFirstResult, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getSingleResultOrNull, isBound, unwrap

Method Details

getQueryString

String getQueryString()

The Query as a string, or null in the case of a criteria query.

asSelectionQuery

SelectionQuery<T> asSelectionQuery()

Description copied from interface: CommonQueryContract

Casts this query as a SelectionQuery.

Specified by:

asSelectionQuery in interface CommonQueryContract

ofType

<R> SelectionQuery<R> ofType(Class<R> type)

Covariant override of Query.ofType(Class).

Specified by:

ofType in interface Query

See Also:

• CommonQueryContract.asSelectionQuery(Class)

API Note:

Jakarta Persistence declares that the generic IllegalStateException exception be thrown, as opposed to something more meaningful like Hibernate's IllegalSelectQueryException.

withEntityGraph

<R> SelectionQuery<R> withEntityGraph(EntityGraph<R> entityGraph)

Covariant override of Query.withEntityGraph(EntityGraph).

Specified by:

withEntityGraph in interface Query

See Also:

• CommonQueryContract.asSelectionQuery(EntityGraph, GraphSemantic)
• SharedSessionContract.createSelectionQuery(String, EntityGraph)
• SharedSessionContract.createQuery(String, EntityGraph)
• CommonQueryContract.asSelectionQuery(Class)

API Note:

Jakarta Persistence declares that the generic IllegalStateException exception be thrown, as opposed to something more meaningful like Hibernate's IllegalSelectQueryException.

asStatement

MutationQuery asStatement()

Covariant override of Query.asStatement().

Specified by:

asStatement in interface Query

See Also:

• CommonQueryContract.asMutationQuery()

API Note:

Jakarta Persistence declares that the generic IllegalStateException exception be thrown, as opposed to something more meaningful like Hibernate's IllegalMutationQueryException.

setQueryFlushMode

Query setQueryFlushMode(QueryFlushMode queryFlushMode)

Description copied from interface: CommonQueryContract

Set the QueryFlushMode to use for this query.

Specified by:

setQueryFlushMode in interface CommonQueryContract

See Also:

• Session.getHibernateFlushMode()

setComment

Query<T> setComment(String comment)

Set the comment for this query.

If SQL commenting is enabled, the comment will be added to the SQL query sent to the database, which may be useful for identifying the source of troublesome queries.

SQL commenting may be enabled using the configuration property "hibernate.use_sql_comments".

Specified by:

setComment in interface CommonQueryContract

See Also:

• CommonQueryContract.getComment()

addQueryHint

Query<T> addQueryHint(String hint)

Add a database query hint to the SQL query.

Multiple query hints may be specified. The operation Dialect.getQueryHintString(String, List) determines how the hint is actually added to the SQL query.

Specified by:

addQueryHint in interface CommonQueryContract

setTimeout

Query<T> setTimeout(int timeout)

Apply a timeout to the corresponding database query.

Specified by:

setTimeout in interface CommonQueryContract

See Also:

• CommonQueryContract.getTimeout()
• Timeouts
• CommonQueryContract.setTimeout(Timeout)

setTimeout

Query<T> setTimeout(Integer timeout)

Apply a timeout to the corresponding database query.

Specified by:

setTimeout in interface CommonQueryContract

Specified by:

setTimeout in interface Query

See Also:

• CommonQueryContract.getTimeout()
• Timeouts
• CommonQueryContract.setTimeout(Timeout)

setTimeout

Query<T> setTimeout(Timeout timeout)

Apply a timeout to the corresponding database query.

Specified by:

setTimeout in interface CommonQueryContract

Specified by:

setTimeout in interface Query

isQueryPlanCacheable

boolean isQueryPlanCacheable()

Whether the execution plan for this Query is cached.

setQueryPlanCacheable

Query<T> setQueryPlanCacheable(boolean queryPlanCacheable)

Enable/disable Query plan caching for this query, if available.

See Also:

• isQueryPlanCacheable()

setHint

Query<T> setHint(String hintName,
 Object value)

Set a hint. Hints are a JPA-standard way to control provider-specific behavior affecting execution of the query. Clients of native Hibernate API should make use of type-safe operations of this interface and of its subtypes. For example, SelectionQuery.setCacheRegion(String) is preferred over HibernateHints.HINT_CACHE_REGION.

The hints understood by Hibernate are enumerated by AvailableHints.

Specified by:

setHint in interface CommonQueryContract

Specified by:

setHint in interface Query

See Also:

• HibernateHints
• SpecHints

setParameter

Query<T> setParameter(String parameter,
 Object argument)

Bind the given argument to a named query parameter.

If the type of the parameter cannot be inferred from the context in which it occurs, use one of the overloads which accepts a "type", or pass a TypedParameterValue.

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• CommonQueryContract.setParameter(String, Object, Class)
• CommonQueryContract.setParameter(String, Object, Type)
• CommonQueryContract.setParameter(int, Object)
• TypedParameterValue

setParameter

<P> Query<T> setParameter(String parameter,
 P argument,
 Class<P> type)

Bind the given argument to a named query parameter using the given Class reference to attempt to infer the Type. If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameter(String, Object).

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• CommonQueryContract.setParameter(String, Object, Type)
• CommonQueryContract.setParameter(int, Object, Class)

setParameter

<P> Query<T> setParameter(String parameter,
 P argument,
 Type<P> type)

Bind the given argument to a named query parameter using the given Type.

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

setParameter

Query<T> setParameter(int parameter,
 Object argument)

Bind the given argument to an ordinal query parameter.

If the type of the parameter cannot be inferred from the context in which it occurs, use one of the overloads which accepts a "type", or pass a TypedParameterValue.

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• CommonQueryContract.setParameter(int, Object, Class)
• CommonQueryContract.setParameter(int, Object, Type)
• CommonQueryContract.setParameter(String, Object)
• TypedParameterValue

setParameter

<P> Query<T> setParameter(int parameter,
 P argument,
 Class<P> type)

Bind the given argument to an ordinal query parameter using the given Class reference to attempt to infer the Type. If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameter(int, Object).

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• CommonQueryContract.setParameter(int, Object, Type)

setParameter

<P> Query<T> setParameter(int parameter,
 P argument,
 Type<P> type)

Bind the given argument to an ordinal query parameter using the given Type.

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

setParameter

<P> Query<T> setParameter(QueryParameter<P> parameter,
 P argument)

Bind an argument to the query parameter represented by the given QueryParameter.

If the type of the parameter cannot be inferred from the context in which it occurs, use one of the overloads which accepts a "type".

Specified by:

setParameter in interface CommonQueryContract

Parameters:

parameter - the query parameter memento

argument - the argument, which might be null

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameter(QueryParameter, Object, Type)

setParameter

<P> Query<T> setParameter(QueryParameter<P> parameter,
 P argument,
 Class<P> type)

Bind an argument to the query parameter represented by the given QueryParameter, using the given Class reference to attempt to infer the Type to use. If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameter(QueryParameter, Object).

Specified by:

setParameter in interface CommonQueryContract

Parameters:

parameter - the query parameter memento

argument - the argument, which might be null

type - a Type representing the type of the parameter

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameter(QueryParameter, Object, Type)

setParameter

<P> Query<T> setParameter(QueryParameter<P> parameter,
 P argument,
 Type<P> type)

Bind an argument to the query parameter represented by the given QueryParameter, using the given Type.

Specified by:

setParameter in interface CommonQueryContract

Parameters:

parameter - the query parameter memento

argument - the argument, which might be null

type - a Type representing the type of the parameter

Returns:

this, for method chaining

setParameter

<P> Query<T> setParameter(Parameter<P> parameter,
 P argument)

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(Parameter, Object)

setConvertedParameter

<P> Query<T> setConvertedParameter(String name,
 P value,
 Class<? extends AttributeConverter<P,?>> converter)

Specified by:

setConvertedParameter in interface CommonQueryContract

Specified by:

setConvertedParameter in interface Query

See Also:

• Query.setConvertedParameter(String, Object, Class)

setConvertedParameter

<P> Query<T> setConvertedParameter(int position,
 P value,
 Class<? extends AttributeConverter<P,?>> converter)

Specified by:

setConvertedParameter in interface CommonQueryContract

Specified by:

setConvertedParameter in interface Query

See Also:

• Query.setConvertedParameter(int, Object, Class)

setProperties

Query<T> setProperties(Object bean)

Bind the property values of the given bean to named parameters of the query, matching property names with parameter names and mapping property types to Hibernate types using heuristics.

Specified by:

setProperties in interface CommonQueryContract

Parameters:

bean - any JavaBean or POJO

Returns:

this, for method chaining

setProperties

Query<T> setProperties(Map bean)

Bind the values of the given Map to named parameters of the query, matching key names with parameter names and mapping value types to Hibernate types using heuristics.

Specified by:

setProperties in interface CommonQueryContract

Parameters:

bean - a Map of names to arguments

Returns:

this, for method chaining

setParameterList

Query<T> setParameterList(String parameter,
 Collection arguments)

Bind multiple arguments to a named query parameter.

The "type mapping" for the binding is inferred from the type of the first collection element.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(java.lang.String, java.util.Collection, Type)

setParameterList

<P> Query<T> setParameterList(String parameter,
 Collection<? extends P> arguments,
 Class<P> javaType)

Bind multiple arguments to a named query parameter using the given Class reference to attempt to infer the Type If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameterList(String, Collection).

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(java.lang.String, java.util.Collection, Type)

setParameterList

<P> Query<T> setParameterList(String parameter,
 Collection<? extends P> arguments,
 Type<P> type)

Bind multiple arguments to a named query parameter using the given Type.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

Query<T> setParameterList(String parameter,
 Object[] values)

Bind multiple arguments to a named query parameter.

The "type mapping" for the binding is inferred from the type of the first collection element

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(String parameter,
 P[] arguments,
 Class<P> javaType)

Bind multiple arguments to a named query parameter using the given Class reference to attempt to determine the Type to use. If unable to determine an appropriate Type, CommonQueryContract.setParameterList(String, Collection) is used

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(java.lang.String, Object[], Type)

setParameterList

<P> Query<T> setParameterList(String parameter,
 P[] arguments,
 Type<P> type)

Bind multiple arguments to a named query parameter using the given Type.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

Query<T> setParameterList(int parameter,
 Collection arguments)

Bind multiple arguments to an ordinal query parameter.

The "type mapping" for the binding is inferred from the type of the first collection element

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(int parameter,
 Collection<? extends P> arguments,
 Class<P> javaType)

Bind multiple arguments to an ordinal query parameter using the given Class reference to attempt to infer the Type. If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameterList(String, Collection).

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(int, Collection, Type)

setParameterList

<P> Query<T> setParameterList(int parameter,
 Collection<? extends P> arguments,
 Type<P> type)

Bind multiple arguments to an ordinal query parameter using the given Type.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

Query<T> setParameterList(int parameter,
 Object[] arguments)

Bind multiple arguments to an ordinal query parameter.

The "type mapping" for the binding is inferred from the type of the first collection element

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(int parameter,
 P[] arguments,
 Class<P> javaType)

Bind multiple arguments to an ordinal query parameter using the given Class reference to attempt to infer the Type. If unable to infer an appropriate Type, fall back to CommonQueryContract.setParameterList(String, Collection).

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(int, Object[], Type)

setParameterList

<P> Query<T> setParameterList(int parameter,
 P[] arguments,
 Type<P> type)

Bind multiple arguments to an ordinal query parameter using the given Type.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(QueryParameter<P> parameter,
 Collection<? extends P> arguments)

Bind multiple arguments to the query parameter represented by the given QueryParameter.

The type of the parameter is inferred from the context in which it occurs, and from the type of the first given argument.

Specified by:

setParameterList in interface CommonQueryContract

Parameters:

parameter - the parameter memento

arguments - a collection of arguments

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(QueryParameter<P> parameter,
 Collection<? extends P> arguments,
 Class<P> javaType)

Bind multiple arguments to the query parameter represented by the given QueryParameter using the given Class reference to attempt to infer the Type to use. If unable to infer an appropriate Type, fall back to using CommonQueryContract.setParameterList(String, Collection).

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(QueryParameter, java.util.Collection, Type)

setParameterList

<P> Query<T> setParameterList(QueryParameter<P> parameter,
 Collection<? extends P> arguments,
 Type<P> type)

Bind multiple arguments to the query parameter represented by the given QueryParameter, using the given Type.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(QueryParameter<P> parameter,
 P[] arguments)

Bind multiple arguments to the query parameter represented by the given QueryParameter.

The type of the parameter is inferred between the context in which it occurs, the type associated with the QueryParameter and the type of the first given argument.

Specified by:

setParameterList in interface CommonQueryContract

Parameters:

parameter - the parameter memento

arguments - a collection of arguments

Returns:

this, for method chaining

setParameterList

<P> Query<T> setParameterList(QueryParameter<P> parameter,
 P[] arguments,
 Class<P> javaType)

Bind multiple arguments to the query parameter represented by the given QueryParameter using the given Class reference to attempt to infer the Type to use. If unable to infer an appropriate Type, fall back to using CommonQueryContract.setParameterList(String, Collection).

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

See Also:

• CommonQueryContract.setParameterList(QueryParameter, Object[], Type)

setParameterList

<P> Query<T> setParameterList(QueryParameter<P> parameter,
 P[] arguments,
 Type<P> type)

Bind multiple arguments to the query parameter represented by the given QueryParameter, using the given the Type.

Specified by:

setParameterList in interface CommonQueryContract

Returns:

this, for method chaining

getFetchSize

@Deprecated(since="8.0",
            forRemoval=true)
Integer getFetchSize()

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as fetch size is only relevant for selection queries

Obtain the JDBC fetch size hint in effect for this query. This value is eventually passed along to the JDBC query via Statement.setFetchSize(int). As defined by JDBC, this value is a hint to the driver to indicate how many rows to fetch from the database when more rows are needed.

Returns:

The timeout in seconds

See Also:

• Statement.getFetchSize()
• Statement.setFetchSize(int)
• JdbcSettings.STATEMENT_FETCH_SIZE

Implementation Note:

JDBC expressly defines this value as a hint. Depending on the driver, it may or may not have any effect on the actual query execution and ResultSet processing .

setFetchSize

@Deprecated(since="8.0",
            forRemoval=true)
Query<T> setFetchSize(int fetchSize)

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as fetch size is only relevant for selection queries

Sets a JDBC fetch size hint for the query.

Parameters:

fetchSize - the fetch size hint

Returns:

this, for method chaining

See Also:

• getFetchSize()
• JdbcSettings.STATEMENT_FETCH_SIZE

isReadOnly

boolean isReadOnly()

Should entities and proxies loaded by this Query be put in read-only mode? If the read-only/modifiable setting was not initialized, then the default read-only/modifiable setting for the persistence context i s returned instead.

Returns:

true if the entities and proxies loaded by the query will be put in read-only mode; false otherwise (they will be modifiable)

See Also:

• setReadOnly(boolean)
• The read-only/modifiable setting has no impact on entities/proxies returned by the query that existed in the session beforeQuery the query was executed.

setReadOnly

Query<T> setReadOnly(boolean readOnly)

Set the read-only/modifiable mode for entities and proxies loaded by this Query. This setting overrides the default setting for the persistence context, Session.isDefaultReadOnly().

To set the default read-only/modifiable setting used for entities and proxies that are loaded into the session, use Session.setDefaultReadOnly(boolean).

Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted.

When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the session's current setting.

The read-only/modifiable setting has no impact on entities/proxies returned by the query that existed in the session beforeQuery the query was executed.

Parameters:

readOnly - true indicates that entities and proxies loaded by the query are to be put in read-only mode; false indicates that entities and proxies loaded by the query will be put in modifiable mode

Returns:

this, for method chaining

isCacheable

@Deprecated(since="8.0",
            forRemoval=true)
boolean isCacheable()

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as caching is only relevant for selection queries

Should the results of the query be stored in the second level cache?

This is different to second level caching of any returned entities and collections, which is controlled by getCacheMode().

The query being "eligible" for caching does not necessarily mean its results will be cached. Second-level query caching still has to be enabled on the SessionFactory for this to happen. Usually that is controlled by the configuration setting "hibernate.cache.use_query_cache".

setCacheable

@Deprecated(since="8.0",
            forRemoval=true)
Query<T> setCacheable(boolean cacheable)

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as caching is only relevant for selection queries

Enable/disable second level query (result) caching for this query.

See Also:

• isCacheable()

getCacheMode

@Deprecated(since="8.0",
            forRemoval=true)
CacheMode getCacheMode()

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as caching is only relevant for selection queries

Obtain the CacheMode in effect for this query. By default, the query inherits the CacheMode of the session from which it originates.

The CacheMode here affects the use of entity and collection caches as the query result set is processed. For caching of the actual query results, use isCacheable() and getCacheRegion().

In order for this setting to have any affect, second-level caching must be enabled and the entities and collections must be eligible for storage in the second-level cache.

See Also:

• Session.getCacheMode()

setCacheMode

@Deprecated(since="8.0",
            forRemoval=true)
Query<T> setCacheMode(CacheMode cacheMode)

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as caching is only relevant for selection queries

Set the current CacheMode in effect for this query.

Set it to null to indicate that the CacheMode of the session should be used.

See Also:

• getCacheMode()
• Session.setCacheMode(CacheMode)

getCacheRegion

@Deprecated(since="8.0",
            forRemoval=true)
String getCacheRegion()

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as caching is only relevant for selection queries

Obtain the name of the second level query cache region in which query results will be stored (if they are cached, see the discussion on isCacheable() for more information). null indicates that the default region should be used.

setCacheRegion

@Deprecated(since="8.0",
            forRemoval=true)
Query<T> setCacheRegion(String cacheRegion)

Deprecated, for removal: This API element is subject to removal in a future version.

Use SelectionQuery instead as caching is only relevant for selection queries

Set the name of the cache region where query results should be cached (assuming isCacheable()). null indicates to use the default region.

See Also:

• getCacheRegion()

setCacheStoreMode

@Deprecated(since="8.0")
Query<T> setCacheStoreMode(CacheStoreMode cacheStoreMode)

Deprecated.

Use SelectionQuery instead as second-level cache interaction is only relevant for queries which return results.

Specified by:

setCacheStoreMode in interface Query

setCacheRetrieveMode

@Deprecated(since="8.0")
Query<T> setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)

Deprecated.

Use SelectionQuery instead as second-level cache interaction is only relevant for queries which return results.

Specified by:

setCacheRetrieveMode in interface Query

setMaxResults

@Deprecated(since="8.0")
Query<T> setMaxResults(int maxResults)

Deprecated.

Use SelectionQuery instead as applying result limits is only relevant for queries which return results.

Specified by:

setMaxResults in interface Query

setFirstResult

@Deprecated(since="8.0")
Query<T> setFirstResult(int startPosition)

Deprecated.

Use SelectionQuery instead as applying result limits is only relevant for queries which return results.

Specified by:

setFirstResult in interface Query

setLockMode

@Deprecated(since="8.0")
Query<T> setLockMode(LockModeType lockMode)

Deprecated.

Use SelectionQuery instead as locking are only relevant for queries which return results.

Specified by:

setLockMode in interface Query

getHibernateLockMode

@Deprecated(since="8.0")
LockMode getHibernateLockMode()

Deprecated.

Use SelectionQuery instead as locking are only relevant for queries which return results.

Get the root LockMode for the query, expressed using Hibernate's native LockMode instead of JPA's LockModeType.

See Also:

• Query.getLockMode()

setHibernateLockMode

@Deprecated(since="8.0")
Query<T> setHibernateLockMode(LockMode lockMode)

Deprecated.

Use SelectionQuery instead as locking are only relevant for queries which return results.

Specify the root LockMode for the query using Hibernate's native LockMode.

See Also:

• setLockMode(LockModeType)

getLockTimeout

@Deprecated
Timeout getLockTimeout()

Deprecated.

Use SelectionQuery instead as locking is only relevant for queries which return results.

Timeout applied specifically to pessimistic lock acquisition.

setLockTimeout

@Deprecated
Query<T> setLockTimeout(Timeout lockTimeout)

Deprecated.

Use SelectionQuery instead as locking is only relevant for queries which return results.

Set a timeout to be applied specifically to pessimistic lock acquisition.

See Also:

• getLockTimeout()

setLockScope

@Deprecated(since="8.0")
Query<T> setLockScope(PessimisticLockScope lockScope)

Deprecated.

Use SelectionQuery instead as locking is only relevant for queries which return results.

Apply a scope to any pessimistic locking applied to the query.

Parameters:

lockScope - The lock scope to apply

Returns:

this, for method chaining

setFollowOnLockingStrategy

@Deprecated(since="8.0")
Query<T> setFollowOnLockingStrategy(Locking.FollowOn strategy)

Deprecated.

Use SelectionQuery instead as locking is only relevant for queries which return results.

Control how Hibernate should handle cases where it is determined subsequent SQL queries would be needs to completely accomplish locking as requested.

Parameters:

strategy - The strategy for follow-on locking.

Returns:

this, for method chaining

setFollowOnStrategy

@Deprecated(since="8.0")
Query<T> setFollowOnStrategy(Locking.FollowOn strategy)

Deprecated.

Use SelectionQuery instead as locking is only relevant for queries which return results.

Control how Hibernate should handle cases where it is determined subsequent SQL queries would be needs to completely accomplish locking as requested.

Parameters:

strategy - The strategy for follow-on locking.

Returns:

this, for method chaining

setTupleTransformer

<X> Query<X> setTupleTransformer(TupleTransformer<X> transformer)

Set a TupleTransformer.

setResultListTransformer

Query<T> setResultListTransformer(ResultListTransformer<T> transformer)

Set a ResultListTransformer.

list

@Deprecated(since="8.0")
List<T> list()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the Query results as a List. If the Query contains multiple items in the selection list, then by default each result in the list is packaged in an array of type Object[].

Returns:

the result list

getResultList

@Deprecated(since="8.0")
default List<T> getResultList()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the Query results as a List. If the Query contains multiple items in the selection list, then by default each result in the list is packaged in an array of type Object[].

Specified by:

getResultList in interface Query

Returns:

the results as a list

Implementation Note:

Delegates to list()

scroll

@Deprecated(since="8.0")
ScrollableResults<T> scroll()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the results in a scrollable form.

This overload simply calls scroll(ScrollMode) using the dialect default scroll mode.

API Note:

The exact behavior of this method depends somewhat on the level of JDBC driver support for scrollable ResultSets, and so is not very portable between database.

scroll

@Deprecated(since="8.0")
ScrollableResults<T> scroll(ScrollMode scrollMode)

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the results in a scrollable form. The capabilities of the returned ScrollableResults depend on the specified ScrollMode.

API Note:

The exact behavior of this method depends somewhat on the level of JDBC driver support for scrollable ResultSets, and so is not very portable between database.

getResultStream

@Deprecated(since="8.0")
default Stream<T> getResultStream()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the Query results as a Stream. If the Query contains multiple items in the selection list, then by default each result in the stream is packaged in an array of type Object[].

The client should call BaseStream.close() after processing the stream so that resources are freed as soon as possible.

Specified by:

getResultStream in interface Query

Returns:

The results as a Stream

Implementation Note:

Delegates to stream(), which in turn delegates to this method. Implementors should implement at least one of these methods.

stream

@Deprecated(since="8.0")
default Stream<T> stream()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the Query results as a Stream. If the Query contains multiple items in the selection list, then by default each result in the stream is packaged in an array of type Object[].

The client should call BaseStream.close() after processing the stream so that resources are freed as soon as possible.

Returns:

The results as a Stream

Since:

5.2

uniqueResult

@Deprecated(since="8.0")
T uniqueResult()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the single result of the query, or null if the Query returns no results.

Returns:

the single result or null if there is no result to return

Throws:

NonUniqueResultException - if there is more than one matching result

getSingleResult

@Deprecated(since="8.0")
T getSingleResult()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the single result of the query, throwing an exception if the Query returns no results.

Specified by:

getSingleResult in interface Query

Returns:

the single result, only if there is exactly one

Throws:

NonUniqueResultException - if there is more than one matching result

NoResultException - if there is no result to return

uniqueResultOptional

@Deprecated(since="8.0")
Optional<T> uniqueResultOptional()

Deprecated.

Use SelectionQuery instead for queries which return results.

Execute the Query and return the single result of the Query as an instance of Optional.

Returns:

the single result as an Optional

Throws:

NonUniqueResultException - if there is more than one matching result

executeUpdate

@Deprecated(since="8.0")
int executeUpdate()

Deprecated.

Use MutationQuery instead for queries which mutate data.

Execute an insert, update, or delete statement, and return the number of affected entities.

For use with instances of MutationQuery created using SharedSessionContract.createMutationQuery(String), SharedSessionContract.createNamedMutationQuery(String), SharedSessionContract.createNativeMutationQuery(String), or SharedSessionContract.createMutationQuery(jakarta.persistence.criteria.CriteriaStatement).

Specified by:

executeUpdate in interface Query

Returns:

the number of affected entity instances (may differ from the number of affected rows)

See Also:

• Query.executeUpdate()

API Note:

This method is needed because this interface extends Query, which defines this method. See MutationQuery and SelectionQuery.

getFlushMode

@Deprecated(since="7")
default FlushModeType getFlushMode()

Deprecated.

The JPA FlushModeType in effect for this query. By default, the Query inherits the FlushMode of the Session from which it originates.

Specified by:

getFlushMode in interface Query

See Also:

• CommonQueryContract.getQueryFlushMode()

API Note:

Inherited from Jakarta Persistence. Prefer CommonQueryContract.getQueryFlushMode()

setFlushMode

@Deprecated(since="7")
default Query<T> setFlushMode(FlushModeType flushMode)

Deprecated.

Use setQueryFlushMode(QueryFlushMode) instead.

Set the FlushModeType to use for this query.

Setting this to null ultimately indicates to use the FlushMode of the session. Use setQueryFlushMode(QueryFlushMode) passing QueryFlushMode.NO_FLUSH instead to indicate that no automatic flushing should occur.

Specified by:

setFlushMode in interface Query

See Also:

• CommonQueryContract.getQueryFlushMode()
• setQueryFlushMode(QueryFlushMode)
• Session.getHibernateFlushMode()

API Note:

Inherited from Jakarta Persistence. Prefer setQueryFlushMode(QueryFlushMode)

getQueryOptions

@Deprecated(since="8.0",
            forRemoval=true)
QueryOptions getQueryOptions()

Deprecated, for removal: This API element is subject to removal in a future version.

The various Query subtypes already expose all relevant options; plus exposing QueryOptions is layer-breaking as it is an SPI contract exposed on an API.

Get the execution options for this Query. Many of the setters of this object update the state of the returned QueryOptions. This is useful because it gives access to s primitive value in its (nullable) wrapper form, rather than the primitive form as required by JPA. This allows us to distinguish whether a value has been explicitly set by the client.

Returns:

Return the encapsulation of this query's options.

setParameter

@Deprecated(since="7")
Query<T> setParameter(Parameter<Calendar> parameter,
 Calendar argument,
 TemporalType temporalType)

Deprecated.

Query override

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(Parameter, Calendar, TemporalType)

setParameter

@Deprecated(since="7")
Query<T> setParameter(Parameter<Date> parameter,
 Date argument,
 TemporalType temporalType)

Deprecated.

Query override

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(Parameter, Date, TemporalType)

setParameter

@Deprecated(since="7")
Query<T> setParameter(String parameter,
 Instant argument,
 TemporalType temporalType)

Deprecated.

Bind an Instant value to the named Query parameter using just the portion indicated by the given TemporalType.

Specified by:

setParameter in interface CommonQueryContract

setParameter

@Deprecated(since="7")
Query<T> setParameter(String parameter,
 Calendar argument,
 TemporalType temporalType)

Deprecated.

Query override

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(String, Calendar, TemporalType)

setParameter

@Deprecated(since="7")
Query<T> setParameter(String parameter,
 Date argument,
 TemporalType temporalType)

Deprecated.

Query override

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(String, Date, TemporalType)

setParameter

@Deprecated(since="7")
Query<T> setParameter(int parameter,
 Instant argument,
 TemporalType temporalType)

Deprecated.

Bind an Instant value to the ordinal Query parameter using just the portion indicated by the given TemporalType.

Specified by:

setParameter in interface CommonQueryContract

setParameter

@Deprecated(since="7")
Query<T> setParameter(int parameter,
 Date argument,
 TemporalType temporalType)

Deprecated.

Query override

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(int, Date, TemporalType)

setParameter

@Deprecated(since="7")
Query<T> setParameter(int parameter,
 Calendar argument,
 TemporalType temporalType)

Deprecated.

Query override

Specified by:

setParameter in interface CommonQueryContract

Specified by:

setParameter in interface Query

See Also:

• Query.setParameter(int, Calendar, TemporalType)