Spring Data JPA 6.x Pageable Migration: Keyset Pagination Absence in Standard API

Direct answer

Spring Data JPA 6.x does **not** provide an extension point to replace offset‑based pagination with keyset pagination while keeping the Pageable contract, and a custom Pageable implementation cannot safely substitute PageRequest without breaking repository internals.

Confirmed facts

• The Pageable interface and its default implementation PageRequest store offset and page size as final fields; Spring Data JPA’s SimpleJpaRepository.readPage() casts the incoming Pageable to PageRequest to extract those values.
• Query derivation (via QueryDslJpaRepository or SimpleJpaRepository) always appends LIMIT ? OFFSET ? clauses; there is no hook to alter the generated SQL to a WHERE … > :seek form.
• Spring Data 2024.x (the baseline for Spring Boot 3.2) adds only Pageable.toOptional() and Pageable.unpaged(); no keyset‑related methods appear in the API.

Likely explanation

The pagination abstraction in Spring Data Commons was designed around offset/limit semantics because they work uniformly across relational databases and require no ordering assumptions. Keyset (seek) pagination needs a deterministic, immutable sort key and a WHERE clause that mirrors the ORDER BY, which cannot be expressed by merely swapping offset/page size values.

Steps to adopt keyset pagination while staying within Spring Data JPA

1. Identify a suitable seek key: a column (or tuple) that is unique, immutable, and ordered the same way as the desired Sort (typically the primary key or a composite key with a fixed order).
2. Add a custom repository method that encodes the seek predicate manually, e.g.:

   @Repository
   public interface OrderRepository extends JpaRepository {
       @Query("SELECT o FROM Order o WHERE o.id > :lastId ORDER BY o.id")
       Slice findAfter(@Param("lastId") Long lastId, Pageable pageable);
   }
   

   The method receives a Pageable only to reuse its pageSize and Sort (the sort must match the seek key; otherwise the method should ignore or reject it).
3. Return a type that fits keyset semantics: use Slice (which avoids the costly count query) or define a custom wrapper such as KeysetPage<T> that holds the content and the next‑seek value. Page is unsuitable because it implies a total count and page numbers that keyset pagination cannot provide.
4. Preserve Sort integration only when static: if the API must allow dynamic ordering, keyset pagination cannot be used safely; you must either restrict the allowed sort options to the seek key or fall back to offset‑based pagination for those cases.
5. Test the implementation: verify that the generated SQL contains a WHERE clause on the seek key and a LIMIT (no OFFSET), and that hasNext() works by fetching limit+1 records.

Implications for Page vs Slice

• Page: requires a total count query; keyset pagination cannot efficiently provide this, so using Page would re‑introduce the performance problem you are trying to avoid.
• Slice: avoids the count query and only needs to know whether there is a next page. With keyset pagination you can implement hasNext() by checking if the extra‑record fetch returned a result, making Slice a compatible return type.

Missing diagnostic detail

If you cannot guarantee a unique, immutable sort key (e.g., your table lacks a suitable column or you need to sort on mutable fields), keyset pagination is not viable and you should stay with offset‑based pagination or consider a third‑party library that handles more complex seek predicates.

Verification suggestions

• Inspect org.springframework.data.domain.PageRequest source (Spring Data Commons 3.2.x) to confirm offset/limit are final and no keyset methods exist.
• Check org.springframework.data.jpa.repository.support.SimpleJpaRepository.readPage() (Spring Data JPA 3.2.x) for the Pageable cast to PageRequest.
• Run a test repository with the custom method above and enable SQL logging; verify the absence of OFFSET and presence of a WHERE clause on the seek key.