Package org.hibernate.query

Class KeyedPage<R>

java.lang.Object
org.hibernate.query.KeyedPage<R>
@Incubating public class KeyedPage<R> extends Object
Support for pagination based on a unique key of the result set instead of the offset.

In this context, a key is a unique key of the query result set which imposes a total order on the results. It is represented as a List<Order<? super R>> where R is the result type of the query. For example, a unique key for paginating a query result set containing Books might be: 

 var key = List.of(asc(Book_.title), asc(Book_.publicationDate), asc(Book_.publisher));

When key-based pagination is used, Hibernate modifies the original HQL or criteria query to incorporate the key in the order by, where, and select clauses.

A specification for an initial page may be obtained from an instance of Page. 

 KeyedPage<Book> firstPage = Page.first(10).keyedBy(asc(Book_.isbn)));
A KeyedResultList then may be obtained by calling SelectionQuery.getKeyedResultList(KeyedPage). 
 KeyedResultList results =
         session.createQuery("from Book", Book.class)
                .getKeyedResultList(firstPage);
The following page may be obtained from KeyedResultList.getNextPage(). 
 KeyedPage<Book> nextPage = results.getNextPage();
 KeyedResultList moreResults =
         session.createQuery("from Book", Book.class)
                .getKeyedResultList(nextPage);

A parameter of a finder method or HQL query method may be declared with type Page. Then the return type of the method should be KeyedResultList.

Since:
6.5
See Also:

  • Method Details

    • getKeyDefinition

      public List<Order<? super R>> getKeyDefinition()
      A key definition for key-based pagination. The list of Order objects must define a total ordering of the query result set, and thus forms a unique key on the result set.

    • getPage

      public Page getPage()
      A specification of this page in terms of page size and an (approximate) page number.

    • getKey

      public List<Comparable<?>> getKey()
      The key of the last result on the previous page, or of the first result on the next page, which may be used to locate the start or end, respectively, of the current page.

      A null key indicates that an offset should be used instead. This is used to obtain an initial page of results.

      Returns:
      the key, or null if an offset should be used

    • getKeyInterpretation

      public KeyedPage.KeyInterpretation getKeyInterpretation()
      Determines whether the key should be interpreted as the last result on the previous page, or as the first result on the next page.

    • nextPage

      @Internal public KeyedPage<R> nextPage(List<Comparable<?>> keyOfLastResultOnThisPage)
      Obtain a specification of the next page of results, which is to be located using the given key, which must be the key of the last result on this page.
      Parameters:
      keyOfLastResultOnThisPage - the key of the last result on this page
      Returns:
      a KeyedPage representing the next page of results

    • previousPage

      @Internal public KeyedPage<R> previousPage(List<Comparable<?>> keyOfFirstResultOnThisPage)
      Obtain a specification of the previous page of results, which is to be located using the given key, which must be the key of the first result on this page.
      Parameters:
      keyOfFirstResultOnThisPage - the key of the first result on this page
      Returns:
      a KeyedPage representing the next page of results

    • withKey

      @Internal public KeyedPage<R> withKey(List<Comparable<?>> key, KeyedPage.KeyInterpretation interpretation)
      Attach the given key to the specification of this page, with the given interpretation.
      Returns:
      a KeyedPage representing the same page of results, but which may be located using the given key