Pagination and Sorting with Pageable

Returning an entire table in one response does not scale — a products table with 500,000 rows should never be fetched in a single query for a listing page. Spring Data JPA builds pagination and sorting directly into the repository abstraction through the Pageable and Page types, so paging works consistently across every repository without custom SQL.

Pageable and PageRequest

Pageable is an interface describing a page request: which page number, how many items per page, and optional sort order. PageRequest.of(page, size, sort) is the standard way to construct one. Any repository method can accept a Pageable parameter as long as it either overrides a JpaRepository method or is declared to return a Page/Slice/List.

The Page<T> Response

A repository method returning Page<T> gives back not just the requested slice of data but also metadata: total number of elements, total number of pages, whether this is the first/last page, and the current page number. This is exactly the metadata a frontend needs to render pagination controls without a separate count query.

Accepting Pagination Parameters from the Client

Spring MVC can bind an incoming Pageable directly from query parameters (e.g. ?page=0&size=20&sort=price,desc) when a controller method parameter is typed as Pageable — Spring Data Web support resolves it automatically, so you rarely construct PageRequest by hand inside a controller.

Defaults and Limits

When the client sends no paging parameters, Spring Boot uses page 0 with 20 items and no sort. @PageableDefault(size = 10, sort = "price", direction = DESC) on the controller parameter sets a different default for one endpoint. Clients can never ask for an unlimited page: size is capped at 2000 by default, and you can lower that cap with spring.data.web.pageable.max-page-size. A request for ?size=5000 then quietly gets the cap instead.

Returning Stable JSON

If a controller returns a Page directly, Spring Data logs a warning on the first request: "Serializing PageImpl instances as-is is not supported, meaning that there is no guarantee about the stability of the resulting JSON structure". The default JSON carries internal fields such as pageable.paged and sort.unsorted, and their names may change between versions. Set spring.data.web.pageable.serialization-mode=via-dto and the response becomes a small, stable shape: content plus a page object with size, number, totalElements and totalPages. If you configure this with @EnableSpringDataWebSupport(pageSerializationMode = VIA_DTO) instead, note that declaring that annotation turns off Spring Boot's own paging configuration, so the spring.data.web.pageable.* properties above stop working.

Page or Slice?

Page runs a second COUNT query so it can report totalElements and totalPages, which you need for numbered pagination ("page 3 of 12"). Slice skips the count and only knows whether another slice exists, which is all an infinite-scroll feed or a "Load more" button needs. On a large table the count query can cost as much as the page itself, so choose Slice when nobody looks at the total. For very deep pages, offset paging gets slower because the database still walks past every skipped row; Spring Data's keyset scrolling (ScrollPosition and Window) avoids that by continuing from the last row seen.

Example

public interface ProductRepository extends JpaRepository<Product, Long> {
    Page<Product> findByCategory(String category, Pageable pageable);
    Slice<Product> findSliceByCategory(String category, Pageable pageable);
}

@RestController
@RequestMapping("/api/products")
public class ProductController {
    private final ProductRepository repository;
    public ProductController(ProductRepository repository) { this.repository = repository; }

    @GetMapping
    public Page<Product> list(@RequestParam String category,
                              @PageableDefault(size = 2, sort = "price", direction = Sort.Direction.DESC) Pageable pageable) {
        return repository.findByCategory(category, pageable);
    }

    @GetMapping("/feed")
    public Slice<Product> feed(@RequestParam String category, Pageable pageable) {
        return repository.findSliceByCategory(category, pageable);
    }
}

# application.properties
spring.data.web.pageable.serialization-mode=via-dto
spring.data.web.pageable.max-page-size=50

GET /api/products?category=Electronics
{"content":[{"name":"Mechanical Keyboard","category":"Electronics","price":89.00,"stock":12,"id":3},
            {"name":"Phone Stand","category":"Electronics","price":14.50,"stock":14,"id":2}],
 "page":{"size":2,"number":0,"totalElements":3,"totalPages":2}}

GET /api/products?category=Electronics&size=5000
-> "page":{"size":50,"number":0,"totalElements":3,"totalPages":1}   (size capped at 50)

GET /api/products/feed?category=Electronics&size=2
-> a Slice: "content", "first", "last", "number", "size" ... but no totalElements or totalPages

Exercise

A teammate is about to make this mistake: Fetching the entire table into memory and paginating it in Java code instead of pushing LIMIT/OFFSET down to the database via Pageable. Use Pageable and PageRequest to review the decision. Write a corrected implementation or design sketch that follows Pageable describes a page request (number, size, sort); PageRequest.of() is the standard way to build one., then name one edge case you would check.

Quick quiz

Interview questions