Package org.hibernate.query

Interface QueryProducer

All Known Subinterfaces:
EventSource, QueryProducerImplementor, Session, SessionImplementor, SharedSessionContract, SharedSessionContractImplementor, StatelessSession
All Known Implementing Classes:
AbstractDelegateSessionImplementor, AbstractSharedSessionContract, SessionDelegatorBaseImpl, SessionImpl, SessionLazyDelegator, SharedSessionDelegatorBaseImpl, StatelessSessionImpl, ToOneDelegateSessionImplementor
public interface QueryProducer
An object which can produce instances of SelectionQuery and MutationQuery. Implementors include Session and StatelessSession. Many operations of the interface have the same or very similar signatures to operations of EntityManager. They are declared here to allow reuse by StatelessSession.

There are three fundamental ways to express a query:

  • in Hibernate Query Language, an object-oriented query dialect of SQL which is a superset of the Jakarta Persistence Query Language,
  • in the native SQL dialect of the database, or
  • using the Criteria API defined by JPA, along with extensions defined by Hibernate.

In each case, the object used to execute the query depends on whether the query is a selection query or a mutation query.

  • selection queries are executed via an instance of SelectionQuery, while
  • mutation queries are executed via an instance of MutationQuery, but
  • since JPA makes no such distinction within its API, the type Query is a mixin of SelectionQuery, MutationQuery, and TypedQuery.
This interface declares operations for creating instances of these objects.
Selection Mutation
HQL createSelectionQuery(String,Class) and createSelectionQuery(String,EntityGraph) createMutationQuery(String)
SQL createNativeQuery(String,Class) and createNativeQuery(String,String,Class) createNativeMutationQuery(String)
Criteria createSelectionQuery(CriteriaQuery) createMutationQuery(CriteriaUpdate), createMutationQuery(CriteriaDelete), and createMutationQuery(JpaCriteriaInsert)
Named queries createNamedSelectionQuery(String,Class) createNamedMutationQuery(String)

Operations like createSelectionQuery(), createNamedSelectionQuery(), and createNativeQuery() accept a Java class object indicating the result type of the query.

  • The result type might be an entity class, when the query returns an entity: 
     List<Book> allBooks =
         session.createNativeQuery("select * from books order by title", Book.class)
                 .getResultList();
  • It might be a basic type like String or Long: 
     List<String> allTitles =
         session.createNativeQuery("select distinct title from books order by title", String.class)
                 .getResultList();
  • Finally, the result type might be a class used to package the elements of a select list, such as a Java record with an appropriate constructor, Map, List, or Object[]: 
     record IsbnAndTitle(String isbn, String title) {}

 List<IsbnAndTitle> allBooks =
         session.createNativeQuery("select isbn, title from books order by title", IsbnAndTitle.class)
                 .getResultList();
For a criteria query, the result type is already determined by AbstractQuery.getResultType().
API Note:
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.

  • Method Details

    • createQuery

      @Deprecated(since="6.0") Query createQuery(String queryString)
      Deprecated.
      The overloaded form createQuery(String, Class) which takes a result type is strongly recommended in preference to this method, since it returns a typed Query object, and because it is able to use the given result type to infer the select list, and even sometimes the from clause. Alternatively, createSelectionQuery(String, Class) is preferred for queries, and createMutationQuery(String) for insert, update, and delete statements.
      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, and it has no non-fetch joins, then that root entity is the only element of the select list, or
      • if there is an entity with the alias this, then that entity is the only element of the select list, or
      • otherwise, the query is considered ambiguous, and this method throws a SemanticException.

      The query must have an explicit from clause, which can never be inferred.

      Parameters:
      queryString - The HQL query
      Returns:
      The Query instance for manipulation and execution
      See Also:
      API Note:
      Returns a raw Query type instead of a wildcard type Query<?>, to match the signature of the JPA method EntityManager.createQuery(String).

    • createQuery

      <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[], List, Map, or 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.

      If a query has no explicit from clause, and the given result type is an entity type, the root entity is inferred to be the result type.

      Passing Object.class as the query result type is not recommended. In this special case, this method has the same semantics as the overload createQuery(String).

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

      Parameters:
      queryString - The HQL query
      resultClass - The Class object representing the query result type, which should not be Object.class
      Returns:
      The Query instance for manipulation and execution
      See Also:

    • createQuery

      <R> Query<R> createQuery(TypedQueryReference<R> typedQueryReference)
      Create a typed Query instance for the given typed query reference.
      Parameters:
      typedQueryReference - the type query reference
      Returns:
      The Query instance for execution
      Throws:
      IllegalArgumentException - if a query has not been defined with the name of the typed query reference or if the query result is found to not be assignable to result class of the typed query reference
      See Also:

    • createQuery

      <R> Query<R> createQuery(CriteriaQuery<R> criteriaQuery)
      Create a Query for the given JPA CriteriaQuery.

    • createQuery

      @Deprecated(since="6.0") Query createQuery(CriteriaUpdate updateQuery)
      Deprecated.
      use createMutationQuery(CriteriaUpdate)
      Create a MutationQuery for the given JPA CriteriaUpdate

    • createQuery

      @Deprecated(since="6.0") Query createQuery(CriteriaDelete deleteQuery)
      Deprecated.
      use createMutationQuery(CriteriaDelete)
      Create a MutationQuery for the given JPA CriteriaDelete

    • createNativeQuery

      @Deprecated(since="6.0") NativeQuery createNativeQuery(String sqlString)
      Deprecated.
      use createNativeQuery(String, Class)
      Create a NativeQuery instance for the given native SQL query.
      Parameters:
      sqlString - a native SQL query string
      Returns:
      The NativeQuery instance for manipulation and execution
      See Also:

    • createNativeQuery

      <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 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[], List, Map, or Tuple.
      Parameters:
      sqlString - The native (SQL) query string
      resultClass - The Java type to map results to
      Returns:
      The NativeQuery instance for manipulation and execution
      See Also:

    • createNativeQuery

      <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 - Native (SQL) query string
      resultClass - The Java entity class to map results to
      tableAlias - The table alias for columns in the result set
      Returns:
      The NativeQuery instance for manipulation and execution
      See Also:

    • createNativeQuery

      @Deprecated(since="6.0") NativeQuery createNativeQuery(String sqlString, String resultSetMappingName)
      Deprecated.
      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 SqlResultSetMapping annotation.

      Parameters:
      sqlString - The native (SQL) query string
      resultSetMappingName - The explicit result mapping name
      Returns:
      The NativeQuery instance for manipulation and execution
      See Also:

    • createNativeQuery

      <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 SqlResultSetMapping annotation.

      Parameters:
      sqlString - The native (SQL) query string
      resultSetMappingName - The explicit result mapping name
      Returns:
      The NativeQuery instance for manipulation and execution
      See Also:

    • createSelectionQuery

      @Deprecated(since="6.3") SelectionQuery<?> createSelectionQuery(String hqlString)
      Deprecated.
      The overloaded form createSelectionQuery(String, Class) which takes a result type is strongly recommended in preference to this method, since it returns a typed SelectionQuery object, and because it is able to use the given result type to infer the select list, and even sometimes the from clause.
      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, and it has no non-fetch joins, then that root entity is the only element of the select list, or
      • if there is an entity with the alias this, then that entity is the only element of the select list, or
      • otherwise, the query is considered ambiguous, and this method throws a SemanticException.

      The query must have an explicit from clause, which can never be inferred.

      Throws:
      IllegalSelectQueryException - if the given HQL query is an insert, update or delete statement

    • createSelectionQuery

      <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[], List, Map, or 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.

      If a query has no explicit from clause, and the given result type is an entity type, the root entity is inferred to be the result type.

      Passing Object.class as the query result type is not recommended. In this special case, this method has the same semantics as the overload createSelectionQuery(String).

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

      Parameters:
      hqlString - The HQL select query as a string
      resultType - The Class object representing the query result type, which should not be Object.class
      Throws:
      IllegalSelectQueryException - if the given HQL query is an insert, update or delete statement
      See Also:

    • createSelectionQuery

      <R> SelectionQuery<R> createSelectionQuery(String hqlString, EntityGraph<R> resultGraph)
      Create a SelectionQuery instance for the given HQL query string and given EntityGraph, which is interpreted as a load graph. The query result type is the root entity of the given graph.
      • If the query has an explicit select clause, there must be a single item in the select list, and the select item must be assignable to the root type of the given graph.
      • Otherwise, if a query has no explicit select list, the select list is inferred from the given entity graph. The query must have exactly one root entity in the from clause, it must be assignable to the root type of the given graph, and the inferred select list will contain just that entity.

      If a query has no explicit from clause, and the given result type is an entity type, the root entity is inferred to be the result type.

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

      Parameters:
      hqlString - The HQL select query as a string
      resultGraph - An EntityGraph whose root type is the query result type, which is interpreted as a load graph
      Throws:
      IllegalSelectQueryException - if the given HQL query is an insert, update or delete statement
      Since:
      7.0
      See Also:

    • createSelectionQuery

      <R> SelectionQuery<R> createSelectionQuery(CriteriaQuery<R> criteria)
      Create a SelectionQuery reference for the given CriteriaQuery.
      See Also:

    • createMutationQuery

      MutationQuery createMutationQuery(String hqlString)
      Create a MutationQuery reference for the given HQL insert, update, or delete statement.
      Parameters:
      hqlString - The HQL insert, update, or delete statement
      Throws:
      IllegalMutationQueryException - if the given HQL query is a select query

    • createMutationQuery

      MutationQuery createMutationQuery(CriteriaUpdate updateQuery)
      Create a MutationQuery from the given update criteria tree

    • createMutationQuery

      MutationQuery createMutationQuery(CriteriaDelete deleteQuery)
      Create a MutationQuery from the given delete criteria tree

    • createMutationQuery

      MutationQuery createMutationQuery(JpaCriteriaInsert insert)
      Create a MutationQuery from the given insert criteria tree

    • createNativeMutationQuery

      MutationQuery createNativeMutationQuery(String sqlString)
      Create a NativeQuery instance for the given native SQL statement.
      Parameters:
      sqlString - a native SQL statement string
      Returns:
      The NativeQuery instance for manipulation and execution

    • createNamedQuery

      @Deprecated(since="6.0") Query createNamedQuery(String name)
      Deprecated.
      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 - the name of a predefined named query
      Returns:
      The Query instance for manipulation and execution
      Throws:
      IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid
      See Also:

    • createNamedQuery

      <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 - the name of a query defined in metadata
      resultClass - the type of the query result
      Returns:
      The Query instance for manipulation and execution
      Throws:
      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:

    • createNamedSelectionQuery

      @Deprecated(since="6.3") SelectionQuery<?> createNamedSelectionQuery(String name)
      Deprecated.
      use createNamedSelectionQuery(String, Class)
      Create a SelectionQuery instance for the named NamedQuery.
      Throws:
      IllegalSelectQueryException - if the given HQL query is not a select query
      UnknownNamedQueryException - if no query has been defined with the given name
      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.

    • createNamedSelectionQuery

      <R> SelectionQuery<R> createNamedSelectionQuery(String name, Class<R> resultType)
      Create a SelectionQuery instance for the named NamedQuery with the given result type.
      Throws:
      IllegalSelectQueryException - if the given HQL query is not a select query
      UnknownNamedQueryException - if no query has been defined with the given name

    • createNamedMutationQuery

      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.
      Throws:
      IllegalMutationQueryException - if the given HQL query is a select query
      UnknownNamedQueryException - if no query has been defined with the given name

    • getNamedQuery

      @Deprecated(since="6.0") Query getNamedQuery(String queryName)
      Deprecated.
      use createNamedQuery(String, Class)
      Create a Query instance for the named query.
      Parameters:
      queryName - the name of a predefined named query
      Returns:
      The Query instance for manipulation and execution
      Throws:
      IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid

    • getNamedNativeQuery

      @Deprecated(since="6.0") NativeQuery getNamedNativeQuery(String name)
      Deprecated.
      use createNamedQuery(String, Class)
      Get a NativeQuery instance for a named native SQL query
      Parameters:
      name - The name of the predefined query
      Returns:
      The NativeQuery instance for manipulation and execution

    • getNamedNativeQuery

      @Deprecated(since="6.0") NativeQuery getNamedNativeQuery(String name, String resultSetMapping)
      Deprecated.
      use createNamedQuery(String, Class)
      Get a NativeQuery instance for a named native SQL query
      Parameters:
      name - The name of the predefined query
      Returns:
      The NativeQuery instance for manipulation and execution