Package org.hibernate.query

Interface SelectionQuery<R>

All Superinterfaces:
CommonQueryContract
All Known Subinterfaces:
NativeQuery<T>, NativeQueryImplementor<R>, ProcedureCallImplementor<R>, Query<R>, QueryImplementor<R>, SqmQueryImplementor<R>, SqmSelectionQuery<R>, SqmSelectionQueryImplementor<R>
All Known Implementing Classes:
AbstractQuery, AbstractSelectionQuery, DelegatingSqmSelectionQueryImplementor, NativeQueryImpl, ProcedureCallImpl, QuerySqmImpl, SqmSelectionQueryImpl
@Incubating public interface SelectionQuery<R> extends CommonQueryContract
Within the context of an active session, an instance of this type represents an executable selection query, that is, a select. It is a slimmed-down version of Query, providing only methods relevant to selection queries.

A SelectionQuery may be obtained from the Session by calling:

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

A query which returns multiple results should be executed via getResultList(): 
 List<Book> books =
         session.createSelectionQuery("from Book left join fetch authors where title like :title")
                 .setParameter("title", title)
                 .setMaxResults(50)
                 .getResultList();
A query which is expected to return exactly one on result should be executed via getSingleResult(), or, if it might not return a result, getSingleResultOrNull(): 
 Book book =
         session.createSelectionQuery("from Book where isbn = ?1")
                 .setParameter(1, isbn)
                 .getSingleResultOrNull();

A query may have explicit fetch joins, specified using the syntax join fetch in HQL, or via FetchParent.fetch(jakarta.persistence.metamodel.SingularAttribute<? super X, Y>) in the criteria API. Additional fetch joins may be added by:

The special built-in fetch profile named "org.hibernate.defaultProfile" adds a fetch join for every eager @ManyToOne or @OneToOne association belonging to an entity returned by the query.

Finally, two alternative approaches to pagination are available:

  1. The operations and setOrder(List) and setPage(Page), together with Order and Page, provide a streamlined API for offset-based pagination, at a slightly higher semantic level than the ancient but dependable setFirstResult(int) and setMaxResults(int).
  2. On the other hand, KeyedPage and KeyedResultList, along with getKeyedResultList(KeyedPage), provide for key-based pagination, which can help eliminate missed or duplicate results when data is modified between page requests.