Top Description Methods
org.hibernate.query

public Interface QueryProducer

Known Direct Subinterfaces
org.hibernate.query.spi.QueryProducerImplementor, org.hibernate.SharedSessionContract
Imports
org.hibernate.query.criteria.JpaCriteriaInsertSelect, jakarta.persistence.criteria.CriteriaDelete, .CriteriaQuery, .CriteriaUpdate
Contract for things that can produce instances of Query and NativeQuery. Implementors include org.hibernate.Session and org.hibernate.StatelessSession. Many operations of the interface have the same or very similar signatures to operations of jakarta.persistence.EntityManager. They are declared here to allow reuse by StatelessSession.

Unlike the corresponding operations of EntityManager, operations for creating untyped instances of Query are all marked as deprecated. Clients must migrate to the use of the equivalent operations which accept a Class and return a typed Query.

Author
Steve Ebersole

Method Summary

Modifier and TypeMethod and Description
public MutationQuery
createMutationQuery(String hqlString)

Create a MutationQuery reference for the given HQL insert, update, or delete statement.

public MutationQuery
createMutationQuery(CriteriaUpdate<T> updateQuery)

Create a MutationQuery from the given update criteria tree

public MutationQuery
createMutationQuery(CriteriaDelete<T> deleteQuery)

Create a MutationQuery from the given delete criteria tree

public MutationQuery
createMutationQuery(JpaCriteriaInsertSelect<T> insertSelect)

Create a MutationQuery from the given insert-select criteria tree

public MutationQuery
createNamedMutationQuery(String name)

Create a MutationQuery instance for the given named insert, update, or delete HQL query.

public Query<R>

Returns:

The Query instance for manipulation and execution
createNamedQuery(String
the name of a predefined named query
name)

Deprecated since 6.0. use createNamedQuery(String, Class)
Create a typed Query instance for the given named query.
public <R> Query<R>

Returns:

The Query instance for manipulation and execution
createNamedQuery(String
the name of a query defined in metadata
name, Class<R>
the type of the query result
resultClass)

Create a typed Query instance for the given named query.

public SelectionQuery<?>
createNamedSelectionQuery(String name)

Deprecated since 6.3. use createNamedSelectionQuery(String, Class)
Create a SelectionQuery instance for the named jakarta.persistence.NamedQuery.
public <R> SelectionQuery<R>
createNamedSelectionQuery(String name, Class<R> resultType)

Create a SelectionQuery instance for the named jakarta.persistence.NamedQuery with the given result type.

public MutationQuery

Returns:

The NativeQuery instance for manipulation and execution
createNativeMutationQuery(String
a native SQL statement string
sqlString)

Create a NativeQuery instance for the given native SQL statement.

public NativeQuery<T>

Returns:

The NativeQuery instance for manipulation and execution
createNativeQuery(String
a native SQL query string
sqlString)

Deprecated since 6.0. use createNativeQuery(String, Class)
Create a NativeQuery instance for the given native SQL query.
public <R> NativeQuery<R>

Returns:

The NativeQuery instance for manipulation and execution
createNativeQuery(String
The native (SQL) query string
sqlString, Class<R>
The Java type to map results to
resultClass)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java type.

public <R> NativeQuery<R>

Returns:

The NativeQuery instance for manipulation and execution
createNativeQuery(String
Native (SQL) query string
sqlString, Class<R>
The Java entity class to map results to
resultClass, String
The table alias for columns in the result set
tableAlias)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java entity type.

public NativeQuery<T>

Returns:

The NativeQuery instance for manipulation and execution
createNativeQuery(String
The native (SQL) query string
sqlString, String
The explicit result mapping name
resultSetMappingName)

Deprecated since 6.0. use createNativeQuery(String, String, Class)
Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.
public <R> NativeQuery<R>

Returns:

The NativeQuery instance for manipulation and execution
createNativeQuery(String
The native (SQL) query string
sqlString, String
The explicit result mapping name
resultSetMappingName, Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.

public Query<R>

Returns:

The Query instance for manipulation and execution
createQuery(String
The HQL query
queryString)

Deprecated since 6.0. use createQuery(String, Class), createSelectionQuery(String, Class), or createMutationQuery(String) depending on intention
Create a Query instance for the given HQL query, or HQL insert, update, or delete statement.
public <R> Query<R>

Returns:

The Query instance for manipulation and execution
createQuery(String
The HQL query
queryString, Class<R>
The type of the query result
resultClass)

Create a typed Query instance for the given HQL query string and given query result type.

public <R> Query<R>
createQuery(CriteriaQuery<R> criteriaQuery)

Create a Query for the given JPA CriteriaQuery.

public Query<R>
createQuery(CriteriaUpdate<T> updateQuery)

Deprecated since 6.0. use createMutationQuery(CriteriaUpdate)
Create a MutationQuery for the given JPA CriteriaUpdate
public Query<R>
createQuery(CriteriaDelete<T> deleteQuery)

Deprecated since 6.0. use createMutationQuery(CriteriaDelete)
Create a MutationQuery for the given JPA CriteriaDelete
public SelectionQuery<?>
createSelectionQuery(String hqlString)

Deprecated since 6.3. Use createSelectionQuery(String, Class)
Create a SelectionQuery reference for the given HQL select statement.
public <R> SelectionQuery<R>
createSelectionQuery(String
The HQL query as a string
hqlString, Class<R>
The Class object representing the query result type
resultType)

Create a SelectionQuery instance for the given HQL query string and given query result type.

public <R> SelectionQuery<R>
createSelectionQuery(CriteriaQuery<R> criteria)

Create a SelectionQuery reference for the given CriteriaQuery.

public NativeQuery<T>

Returns:

The NativeQuery instance for manipulation and execution
getNamedNativeQuery(String
The name of the predefined query
name)

Deprecated since 6.0. use createNamedQuery(String, Class)
Get a NativeQuery instance for a named native SQL query
public NativeQuery<T>

Returns:

The NativeQuery instance for manipulation and execution
getNamedNativeQuery(String
The name of the predefined query
name, String resultSetMapping)

Deprecated since 6.0. use createNamedQuery(String, Class)
Get a NativeQuery instance for a named native SQL query
public Query<R>

Returns:

The Query instance for manipulation and execution
getNamedQuery(String
the name of a predefined named query
queryName)

Deprecated since 6.0. use createNamedQuery(String, Class)
Create a Query instance for the named query.

Method Detail

createMutationQueryback to summary
public MutationQuery createMutationQuery(String hqlString)

Create a MutationQuery reference for the given HQL insert, update, or delete statement.

Exceptions
IllegalMutationQueryException:
if the given HQL query is a select query
createMutationQueryback to summary
public MutationQuery createMutationQuery(CriteriaUpdate<T> updateQuery)

Create a MutationQuery from the given update criteria tree

createMutationQueryback to summary
public MutationQuery createMutationQuery(CriteriaDelete<T> deleteQuery)

Create a MutationQuery from the given delete criteria tree

createMutationQueryback to summary
public MutationQuery createMutationQuery(JpaCriteriaInsertSelect<T> insertSelect)

Create a MutationQuery from the given insert-select criteria tree

createNamedMutationQueryback to summary
public MutationQuery createNamedMutationQuery(String name)

Create a MutationQuery instance for the given named insert, update, or delete HQL query. The named query might be defined as HQL) or native-SQL.

Exceptions
IllegalMutationQueryException:
if the given HQL query is a select query
UnknownNamedQueryException:
if no query has been defined with the given name
createNamedQueryback to summary
public Query<R> createNamedQuery(String name)

Deprecated

since 6.0.

use createNamedQuery(String, Class)

Create a typed Query instance for the given named query. The named query might be defined in HQL or in native SQL.

Parameters
name:String

the name of a predefined named query

Returns:Query<R>

The Query instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
Exceptions
IllegalArgumentException:
if a query has not been defined with the given name or if the query string is found to be invalid
See Also
jakarta.persistence.EntityManager#createNamedQuery(String)
createNamedQueryback to summary
public <R> Query<R> createNamedQuery(String name, Class<R> resultClass)

Create a typed Query instance for the given named query. The named query might be defined in HQL or in native SQL.

Parameters
name:String

the name of a query defined in metadata

resultClass:Class<R>

the type of the query result

Returns:Query<R>

The Query instance for manipulation and execution

Exceptions
IllegalArgumentException:
if a query has not been defined with the given name or if the query string is found to be invalid or if the query result is found to not be assignable to the specified type
See Also
jakarta.persistence.EntityManager#createNamedQuery(String, Class)
createNamedSelectionQueryback to summary
public SelectionQuery<?> createNamedSelectionQuery(String name)

Deprecated

since 6.3.

use createNamedSelectionQuery(String, Class)

Create a SelectionQuery instance for the named jakarta.persistence.NamedQuery.

Implementation Note

This method interprets some queries with an implicit select list in a quite unintuitive way. In some future release, this method will be modified to throw an exception when passed a query with a missing select. For now, use createNamedSelectionQuery(String, Class) to avoid ambiguity.

Annotations
@Deprecated
since:6.3
Exceptions
IllegalSelectQueryException:
if the given HQL query is not a select query
UnknownNamedQueryException:
if no query has been defined with the given name
createNamedSelectionQueryback to summary
public <R> SelectionQuery<R> createNamedSelectionQuery(String name, Class<R> resultType)

Create a SelectionQuery instance for the named jakarta.persistence.NamedQuery with the given result type.

Exceptions
IllegalSelectQueryException:
if the given HQL query is not a select query
UnknownNamedQueryException:
if no query has been defined with the given name
createNativeMutationQueryback to summary
public MutationQuery createNativeMutationQuery(String sqlString)

Create a NativeQuery instance for the given native SQL statement.

Parameters
sqlString:String

a native SQL statement string

Returns:MutationQuery

The NativeQuery instance for manipulation and execution

createNativeQueryback to summary
public NativeQuery<T> createNativeQuery(String sqlString)

Deprecated

since 6.0.

use createNativeQuery(String, Class)

Create a NativeQuery instance for the given native SQL query.

Parameters
sqlString:String

a native SQL query string

Returns:NativeQuery<T>

The NativeQuery instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
See Also
jakarta.persistence.EntityManager#createNativeQuery(String)
createNativeQueryback to summary
public <R> NativeQuery<R> createNativeQuery(String sqlString, Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java type.

  • If the given class is an entity class, this method is equivalent to createNativeQuery(sqlString).addEntity(resultClass).
  • If the given class has a registered org.hibernate.type.descriptor.java.JavaType, then the query must return a result set with a single column whose JdbcType is compatible with that JavaType.
  • Otherwise, the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], java.util.List, java.util.Map, or jakarta.persistence.Tuple.
Parameters
sqlString:String

The native (SQL) query string

resultClass:Class<R>

The Java type to map results to

Returns:NativeQuery<R>

The NativeQuery instance for manipulation and execution

See Also
jakarta.persistence.EntityManager#createNativeQuery(String, Class)
createNativeQueryback to summary
public <R> NativeQuery<R> createNativeQuery(String sqlString, Class<R> resultClass, String tableAlias)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java entity type.

The given class must be an entity class. This method is equivalent to createNativeQuery(sqlString).addEntity(tableAlias, resultClass).

Parameters
sqlString:String

Native (SQL) query string

resultClass:Class<R>

The Java entity class to map results to

tableAlias:String

The table alias for columns in the result set

Returns:NativeQuery<R>

The NativeQuery instance for manipulation and execution

See Also
jakarta.persistence.EntityManager#createNativeQuery(String, Class)
createNativeQueryback to summary
public NativeQuery<T> createNativeQuery(String sqlString, String resultSetMappingName)

Deprecated

since 6.0.

use createNativeQuery(String, String, Class)

Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.

The given result set mapping name must identify a mapping defined by a jakarta.persistence.SqlResultSetMapping annotation.

Parameters
sqlString:String

The native (SQL) query string

resultSetMappingName:String

The explicit result mapping name

Returns:NativeQuery<T>

The NativeQuery instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
See Also
jakarta.persistence.EntityManager#createNativeQuery(String, Class), jakarta.persistence.SqlResultSetMapping
createNativeQueryback to summary
public <R> NativeQuery<R> createNativeQuery(String sqlString, String resultSetMappingName, Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.

The given result set mapping name must identify a mapping defined by a jakarta.persistence.SqlResultSetMapping annotation.

Parameters
sqlString:String

The native (SQL) query string

resultSetMappingName:String

The explicit result mapping name

Returns:NativeQuery<R>

The NativeQuery instance for manipulation and execution

See Also
jakarta.persistence.EntityManager#createNativeQuery(String, Class), jakarta.persistence.SqlResultSetMapping
createQueryback to summary
public Query<R> createQuery(String queryString)

Deprecated

since 6.0.

use createQuery(String, Class), createSelectionQuery(String, Class), or createMutationQuery(String) depending on intention

Create a Query instance for the given HQL query, or HQL insert, update, or delete statement.

If a query has no explicit select list, the select list is inferred:

  • if there is exactly one root entity in the from clause, then that root entity is the only element of the select list, or
  • otherwise, if there are multiple root entities in the from clause, then the select list contains every root entity and every non-fetch joined entity.

API Note

Returns a raw Query type instead of a wildcard type Query<?>, to match the signature of the JPA method jakarta.persistence.EntityManager#createQuery(String).

Implementation Note

This method interprets some queries with an implicit select list in a quite unintuitive way. In some future release, this method will be modified to throw an exception when passed a query with a missing select. For now, use createQuery(String, Class) to avoid ambiguity.

Parameters
queryString:String

The HQL query

Returns:Query<R>

The Query instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
See Also
jakarta.persistence.EntityManager#createQuery(String)
createQueryback to summary
public <R> Query<R> createQuery(String queryString, Class<R> resultClass)

Create a typed Query instance for the given HQL query string and given query result type.

  • If the query has a single item in the select list, then the select item must be assignable to the given result type.
  • Otherwise, if there are multiple select items, then the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], java.util.List, java.util.Map, or jakarta.persistence.Tuple.

If a query has no explicit select list, the select list is inferred from the given query result type:

  • if the result type is an entity type, the query must have exactly one root entity in the from clause, it must be assignable to the result type, and the inferred select list will contain just that entity, or
  • otherwise, the select list contains every root entity and every non-fetch joined entity, and each query result will be packaged into an instance of the result type, just as specified above.

The returned Query may be executed by calling Query#getResultList() or Query#getSingleResult().

Parameters
queryString:String

The HQL query

resultClass:Class<R>

The type of the query result

Returns:Query<R>

The Query instance for manipulation and execution

See Also
jakarta.persistence.EntityManager#createQuery(String, Class)
createQueryback to summary
public <R> Query<R> createQuery(CriteriaQuery<R> criteriaQuery)

Create a Query for the given JPA CriteriaQuery.

createQueryback to summary
public Query<R> createQuery(CriteriaUpdate<T> updateQuery)

Deprecated

since 6.0.

use createMutationQuery(CriteriaUpdate)

Create a MutationQuery for the given JPA CriteriaUpdate

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
createQueryback to summary
public Query<R> createQuery(CriteriaDelete<T> deleteQuery)

Deprecated

since 6.0.

use createMutationQuery(CriteriaDelete)

Create a MutationQuery for the given JPA CriteriaDelete

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
createSelectionQueryback to summary
public SelectionQuery<?> createSelectionQuery(String hqlString)

Deprecated

since 6.3.

Use createSelectionQuery(String, Class)

Create a SelectionQuery reference for the given HQL select statement.

If the statement has no explicit select list, the select list is inferred:

  • if there is exactly one root entity in the from clause, then that root entity is the only element of the select list, or
  • otherwise, if there are multiple root entities in the from clause, then the select list contains every root entity and every non-fetch joined entity.

Implementation Note

This method interprets some queries with an implicit select list in a quite unintuitive way. In some future release, this method will be modified to throw an exception when passed a query with a missing select. For now, use createSelectionQuery(String, Class) to avoid ambiguity.

Annotations
@Deprecated
since:6.3
Exceptions
IllegalSelectQueryException:
if the given HQL query is an insert, update or delete query
createSelectionQueryback to summary
public <R> SelectionQuery<R> createSelectionQuery(String hqlString, Class<R> resultType)

Create a SelectionQuery instance for the given HQL query string and given query result type.

  • If the query has a single item in the select list, then the select item must be assignable to the given result type.
  • Otherwise, if there are multiple select items, then the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], java.util.List, java.util.Map, or jakarta.persistence.Tuple.

If a query has no explicit select list, the select list is inferred from the given query result type:

  • if the result type is an entity type, the query must have exactly one root entity in the from clause, it must be assignable to the result type, and the inferred select list will contain just that entity, or
  • otherwise, the select list contains every root entity and every non-fetch joined entity, and each query result will be packaged into an instance of the result type, just as specified above.

The returned Query may be executed by calling Query#getResultList() or Query#getSingleResult().

Parameters
hqlString:String

The HQL query as a string

resultType:Class<R>

The Class object representing the query result type

Exceptions
IllegalSelectQueryException:
if the given HQL query is an insert, update or delete query
See Also
jakarta.persistence.EntityManager#createQuery(String)
createSelectionQueryback to summary
public <R> SelectionQuery<R> createSelectionQuery(CriteriaQuery<R> criteria)

Create a SelectionQuery reference for the given CriteriaQuery.

See Also
jakarta.persistence.EntityManager#createQuery(CriteriaQuery)
getNamedNativeQueryback to summary
public NativeQuery<T> getNamedNativeQuery(String name)

Deprecated

since 6.0.

use createNamedQuery(String, Class)

Get a NativeQuery instance for a named native SQL query

Parameters
name:String

The name of the predefined query

Returns:NativeQuery<T>

The NativeQuery instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
getNamedNativeQueryback to summary
public NativeQuery<T> getNamedNativeQuery(String name, String resultSetMapping)

Deprecated

since 6.0.

use createNamedQuery(String, Class)

Get a NativeQuery instance for a named native SQL query

Parameters
name:String

The name of the predefined query

Returns:NativeQuery<T>

The NativeQuery instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
getNamedQueryback to summary
public Query<R> getNamedQuery(String queryName)

Deprecated

since 6.0.

use createNamedQuery(String, Class)

Create a Query instance for the named query.

Parameters
queryName:String

the name of a predefined named query

Returns:Query<R>

The Query instance for manipulation and execution

Annotations
@Deprecated
since:6.0
@SuppressWarnings:rawtypes
Exceptions
IllegalArgumentException:
if a query has not been defined with the given name or if the query string is found to be invalid