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.

The method addRestriction(Restriction) allows application of additional filtering to the query results. The static factory methods of Restriction are used to express filtering criteria of various kinds.

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). 
     session.createSelectionQuery("from Book", Book.class)
         .addRestriction(Restriction.contains(Book_.title, "hibernate", false))
         .setOrder(Order.desc(Book_.title))
         .setPage(Page.first(50))
         .getResultList() );
  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.