pagination: Spring Data JPA Page vs Slice vs keyset Window scrolling, with the SQL and REST shapes

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b4bLvQVbZweAqqf54x
This commit is contained in:
Claude
2026-11-16 11:13:56 +05:30
parent e3d1b550ae
commit 91938727f2
42 changed files with 1446 additions and 0 deletions
+12
View File
@@ -0,0 +1,12 @@
# Page<Product> findByCategory("books", PageRequest.of(1, 10, Sort.by("id")))
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id offset ? rows fetch first ? rows only
select count(*) from product p1_0 where p1_0.category=?
statements: 2, rows: 10, totalElements: 25, totalPages: 3, hasNext: true
# Slice<Product> findSliceByCategory("books", PageRequest.of(1, 10, Sort.by("id")))
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id offset ? rows fetch first ? rows only
statements: 1, rows: 10, hasNext: true (no totalElements exists on a Slice)
# List<Product> findListByCategory("books", PageRequest.of(1, 10, Sort.by("id")))
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id offset ? rows fetch first ? rows only
statements: 1, rows: 10 (no total, no hasNext)
+4
View File
@@ -0,0 +1,4 @@
# 5 toys in the table. Does the Slice know whether another slice follows?
slice size 4 -> rows returned: 4, hasNext: true, statements: 1
slice size 5 -> rows returned: 5, hasNext: false, statements: 1
slice size 6 -> rows returned: 5, hasNext: false, statements: 1
@@ -0,0 +1,7 @@
# Page<Product>: how many statements does each request issue? (25 books, 5 toys)
middle page page=1 size=10 rows=10 statements=2 totalElements=25
first page, partial page=0 size=10 rows=5 statements=1 totalElements=5
last page, partial page=2 size=10 rows=5 statements=1 totalElements=25
full page in the middle page=1 size=5 rows=5 statements=2 totalElements=25
last page, exactly full page=4 size=5 rows=5 statements=2 totalElements=25
page past the end page=5 size=10 rows=0 statements=2 totalElements=25
+21
View File
@@ -0,0 +1,21 @@
# derived query, Sort.by("price").descending().and(Sort.by("id"))
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.price desc,p1_0.id fetch first ? rows only
# derived query, unknown property
org.springframework.data.core.PropertyReferenceException
No property 'nope' found for type 'Product'; Did you mean 'name'
# @Query with Sort.by("price").descending() (alias p is applied for you)
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.price desc fetch first ? rows only
select count(*) from product p1_0 where p1_0.category=?
# a value that is not a property reference at all: Sort.by("price) desc, (select 1")
derived -> InvalidDataAccessApiUsageException
Sort expression 'price) desc, (select 1: ASC' must only contain property references or aliases used in the select clause; If you really want to use something other than that for sorting, please use JpaSort.unsafe(…)
@Query -> InvalidDataAccessApiUsageException
Sort expression 'price) desc, (select 1: ASC' must only contain property references or aliases used in the select clause; If you really want to use something other than that for sorting, please use JpaSort.unsafe(…)
# @Query with a function-style sort value, three calls in one fresh context
1. Sort.by("length(name)") -> rejected (InvalidDataAccessApiUsageException)
2. JpaSort.unsafe("length(name)") -> accepted: order by character_length(p1_0.name) fetch first ? rows only
3. Sort.by("length(name)") again -> accepted: order by character_length(p1_0.name) fetch first ? rows only
@@ -0,0 +1,23 @@
# offset paging, third page of 10: PageRequest.of(2, 10, Sort.by("id"))
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id offset ? rows fetch first ? rows only
# keyset scrolling, first window: ScrollPosition.keyset()
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
rows: 10, hasNext: true, position of the last row: KeysetScrollPosition [FORWARD, {id=10}]
# keyset scrolling, second window: the position from the first window
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where (p1_0.category=?) and (p1_0.id>?) order by p1_0.id fetch first ? rows only
rows: 10 (book-11 .. book-20), hasNext: true
# third window: 5 rows (book-21 .. book-25), hasNext: false
# WindowIterator over all 25 books, windows of 10
rows visited: 25, statements: 3
# Query by Example: findBy(example, q -> q.sortBy(Sort.by("id")).limit(5).scroll(ScrollPosition.keyset()))
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
rows: 5, hasNext: true
# offset scrolling: ScrollPosition.offset(0) is a position, so the result starts AFTER it
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id offset ? rows fetch first ? rows only
first row returned: book-2
@@ -0,0 +1,6 @@
# 100,000 rows in category 'bulk'. H2 EXPLAIN ANALYZE reports scanCount: rows the database read.
offset 0, fetch 10 scanCount: 10
offset 90000, fetch 10 scanCount: 90,010
keyset id > 90000, fetch 10 scanCount: 11
These are row counts, not timings. Timings depend on your database, indexes and cache.
@@ -0,0 +1,7 @@
# newest-first feed of 25 books, 5 per page; a new book is inserted between the two requests
offset page 0: [book-25, book-24, book-23, book-22, book-21]
keyset window 0: [book-25, book-24, book-23, book-22, book-21]
-- book-NEW inserted --
offset page 1: [book-21, book-20, book-19, book-18, book-17]
keyset window 1: [book-20, book-19, book-18, book-17, book-16]
offset: book-21 appears on both pages: true
@@ -0,0 +1,7 @@
# newest-first feed of 25 books, 5 per page; book-24 is deleted between the two requests
offset page 0: [book-25, book-24, book-23, book-22, book-21]
keyset window 0: [book-25, book-24, book-23, book-22, book-21]
-- book-24 deleted --
offset page 1: [book-19, book-18, book-17, book-16, book-15]
keyset window 1: [book-20, book-19, book-18, book-17, book-16]
offset skipped book-20: true
@@ -0,0 +1,11 @@
# sorting by price, which repeats: 25 books over 4 distinct prices, pages of 5
rows visited: 25, distinct rows: 25, statements: 5
second statement:
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where (p1_0.category=?) and (p1_0.price>? or p1_0.price=? and p1_0.id>?) order by p1_0.price,p1_0.id fetch first ? rows only
Method 6 names only the price in OrderBy; the id in the statement above was added by Spring Data.
# nullable sort column (H2 sorts NULLs first for ASC)
full window: [b:null, d:null, a:1.00, c:2.00, e:3.00]
after the first row (price null): [d, a, c, e]
select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where (p1_0.category=?) and (p1_0.price is not null or p1_0.price is null and p1_0.id>?) order by p1_0.price,p1_0.id fetch first ? rows only
That predicate is right where NULLs sort first, as on H2. It was not run on a database that sorts them last.
@@ -0,0 +1,4 @@
# a String-based @Query method returning Window<Product>
org.springframework.data.repository.query.QueryCreationException
Scroll queries are not supported using String-based queries
root cause: Scroll queries are not supported using String-based queries
@@ -0,0 +1,11 @@
Spring Data JPA: 4.0.8
# one fresh context, one repository method: findFirst10ByCategoryOrderByIdAsc("books", position)
1. keyset, initial -> book-1..book-10
2. keyset, after book-10 -> book-11..book-20
3. offset, initial -> book-1..book-10
4. offset, after row 10 -> book-11..book-20
5. keyset, after book-10 again -> book-1..book-10 (step 2 returned book-11..book-20)
statement for step 5: select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
# a different method, findFirst5ByCategoryOrderByIdDesc, after the offset calls above
keyset initial -> book-25..book-21, keyset after book-21 -> book-20..book-16
@@ -0,0 +1,11 @@
Spring Data JPA: 4.1.0
# one fresh context, one repository method: findFirst10ByCategoryOrderByIdAsc("books", position)
1. keyset, initial -> book-1..book-10
2. keyset, after book-10 -> book-11..book-20
3. offset, initial -> book-1..book-10
4. offset, after row 10 -> book-11..book-20
5. keyset, after book-10 again -> book-1..book-10 (step 2 returned book-11..book-20)
statement for step 5: select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
# a different method, findFirst5ByCategoryOrderByIdDesc, after the offset calls above
keyset initial -> book-25..book-21, keyset after book-21 -> book-20..book-16
@@ -0,0 +1,11 @@
Spring Data JPA: 4.1.2
# one fresh context, one repository method: findFirst10ByCategoryOrderByIdAsc("books", position)
1. keyset, initial -> book-1..book-10
2. keyset, after book-10 -> book-11..book-20
3. offset, initial -> book-1..book-10
4. offset, after row 10 -> book-11..book-20
5. keyset, after book-10 again -> book-1..book-10 (step 2 returned book-11..book-20)
statement for step 5: select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
# a different method, findFirst5ByCategoryOrderByIdDesc, after the offset calls above
keyset initial -> book-25..book-21, keyset after book-21 -> book-20..book-16
@@ -0,0 +1,25 @@
Hibernate ORM: 7.3.13.Final
# 25 books, 6 of them with 2 reviews each (12 joined rows). Page of 2 products, join fetch p.reviews.
## method 8: @Query("select p from Product p join fetch p.reviews where ...")
select p1_0.id,p1_0.category,p1_0.name,p1_0.price,r1_0.product_id,r1_0.id,r1_0.rating from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.category=? order by p1_0.id
select count(*) from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.category=?
products on the page: [book-1, book-2], reviews loaded on them: 4
entities held by the persistence context: 18
HHH90003004 (applying in memory) logged: true
totalElements reported: 12 (products that actually have reviews: 6)
## method 8b: the same query with countQuery = "select count(distinct p) ..."
select count(distinct p1_0.id) from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.category=?
totalElements reported: 6, totalPages: 3
## method 8c: @EntityGraph(attributePaths = "reviews") on a derived query, page of 4
select p1_0.id,p1_0.category,p1_0.name,p1_0.price,r1_0.product_id,r1_0.id,r1_0.rating from product p1_0 left join review r1_0 on p1_0.id=r1_0.product_id where p1_0.category=? order by p1_0.id
select count(*) from product p1_0 where p1_0.category=?
rows: 4, totalElements: 25, entities held by the persistence context: 37
## methods 9a + 9b: page the ids, then fetch the reviews for exactly those ids
select p1_0.id from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
select count(*) from product p1_0 where p1_0.category=?
select distinct p1_0.id,p1_0.category,p1_0.name,p1_0.price,r1_0.product_id,r1_0.id,r1_0.rating from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.id in (?,?) order by p1_0.id
ids on the page: [1, 2], products fetched: 2, reviews fetched: 4
@@ -0,0 +1,25 @@
Hibernate ORM: 7.4.13.Final
# 25 books, 6 of them with 2 reviews each (12 joined rows). Page of 2 products, join fetch p.reviews.
## method 8: @Query("select p from Product p join fetch p.reviews where ...")
select p1_0.id,p1_0.category,p1_0.name,p1_0.price,r1_0.product_id,r1_0.id,r1_0.rating from (select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? and exists(select 1 from review r1_0 where p1_0.id=r1_0.product_id) order by p1_0.id offset ? rows fetch first ? rows only) p1_0(id,category,name,price) join review r1_0 on p1_0.id=r1_0.product_id order by p1_0.id
select count(*) from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.category=?
products on the page: [book-1, book-2], reviews loaded on them: 4
entities held by the persistence context: 6
HHH90003004 (applying in memory) logged: false
totalElements reported: 12 (products that actually have reviews: 6)
## method 8b: the same query with countQuery = "select count(distinct p) ..."
select count(distinct p1_0.id) from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.category=?
totalElements reported: 6, totalPages: 3
## method 8c: @EntityGraph(attributePaths = "reviews") on a derived query, page of 4
select p1_0.id,p1_0.category,p1_0.name,p1_0.price,r1_0.product_id,r1_0.id,r1_0.rating from (select p1_0.id,p1_0.category,p1_0.name,p1_0.price from product p1_0 where p1_0.category=? order by p1_0.id offset ? rows fetch first ? rows only) p1_0(id,category,name,price) left join review r1_0 on p1_0.id=r1_0.product_id order by p1_0.id
select count(*) from product p1_0 where p1_0.category=?
rows: 4, totalElements: 25, entities held by the persistence context: 12
## methods 9a + 9b: page the ids, then fetch the reviews for exactly those ids
select p1_0.id from product p1_0 where p1_0.category=? order by p1_0.id fetch first ? rows only
select count(*) from product p1_0 where p1_0.category=?
select distinct p1_0.id,p1_0.category,p1_0.name,p1_0.price,r1_0.product_id,r1_0.id,r1_0.rating from product p1_0 join review r1_0 on p1_0.id=r1_0.product_id where p1_0.id in (?,?) order by p1_0.id
ids on the page: [1, 2], products fetched: 2, reviews fetched: 4
@@ -0,0 +1,5 @@
GET /products/echo -> 200 {"sort":"UNSORTED","size":20,"page":0}
GET /products/echo?page=2&size=5&sort=price,desc&sort=id -> 200 {"sort":"price: DESC,id: ASC","size":5,"page":2}
GET /products/echo?size=100000 -> 200 {"sort":"UNSORTED","size":2000,"page":0}
GET /products/echo?page=-3&size=0 -> 200 {"sort":"UNSORTED","size":20,"page":0}
GET /products/echo?page=abc -> 200 {"sort":"UNSORTED","size":20,"page":0}
@@ -0,0 +1,5 @@
GET /products/raw?size=2 (return type Page<ProductView>)
{"content":[{"id":1,"name":"book-1","price":11.00},{"id":2,"name":"book-2","price":12.00}],"empty":false,"first":true,"last":false,"number":0,"numberOfElements":2,"pageable":{"offset":0,"pageNumber":0,"pageSize":2,"paged":true,"sort":{"empty":true,"sorted":false,"unsorted":true},"unpaged":false},"size":2,"sort":{"empty":true,"sorted":false,"unsorted":true},"totalElements":25,"totalPages":13}
GET /products/model?size=2 (return type PagedModel<ProductView>)
{"content":[{"id":1,"name":"book-1","price":11.00},{"id":2,"name":"book-2","price":12.00}],"page":{"size":2,"number":0,"totalElements":25,"totalPages":13}}
+8
View File
@@ -0,0 +1,8 @@
GET /products/raw?size=1&sort=price,desc -> 200
{"content":[{"id":3,"name":"book-3","price":13.00}],"empty":false,"first":true,"last":false,"number":0,"numberOfElements":1,"pageable":{"offset":0,"pageNumber":0,"pageSize":1,"paged":true,"sort":{"empty":false,"sorted":true,"unsorted":false},"unpaged":false},"size":1,"sort":{"empty":false,"sorted":true,"unsorted":false},"totalElements":25,"totalPages":25}
GET /products/raw?size=1&sort=nope -> 400
{"detail":"No property 'nope' found for type 'Product'; Did you mean 'name'","instance":"/products/raw","status":400,"title":"Bad Request"}
GET /products/raw?size=1&sort=price;drop -> 400
{"detail":"Sort expression 'price;drop: ASC' must only contain property references or aliases used in the select clause; If you really want to use something other than that for sorting, please use JpaSort.unsafe(…)","instance":"/products/raw","status":400,"title":"Bad Request"}
GET /products/raw?size=1&sort=,desc -> 200
{"content":[{"id":1,"name":"book-1","price":11.00}],"empty":false,"first":true,"last":false,"number":0,"numberOfElements":1,"pageable":{"offset":0,"pageNumber":0,"pageSize":1,"paged":true,"sort":{"empty":true,"sorted":false,"unsorted":true},"unpaged":false},"size":1,"sort":{"empty":true,"sorted":false,"unsorted":true},"totalElements":25,"totalPages":25}
@@ -0,0 +1,4 @@
GET /products/scroll -> 10 items, nextCursor="MTA"
GET /products/scroll?after=MTA -> 10 items, nextCursor="MjA"
GET /products/scroll?after=MjA -> 5 items, nextCursor=null
calls: 3, items: 25, distinct: 25
@@ -0,0 +1,3 @@
spring.data.web.pageable.serialization-mode=via-dto
GET /products/raw?size=2 (return type Page<ProductView>)
{"content":[{"id":1,"name":"book-1","price":11.00},{"id":2,"name":"book-2","price":12.00}],"page":{"size":2,"number":0,"totalElements":25,"totalPages":13}}