Spring Boot Manual Pagination With Criteria API: A Guide

Aug 13, 2025 by Sebastian Müller 57 views

Manual Pagination in Spring Boot with Criteria API: A Comprehensive Guide

Hey guys! Ever been stuck trying to implement manual pagination using the Criteria API in your Spring Boot application? It can be a bit tricky, especially when you're dealing with legacy code or trying to optimize your queries. In this article, we'll dive deep into how to implement manual pagination with the Criteria API in Spring Boot. We’ll break down the problem, explore the code, and provide a step-by-step guide to get you up and running. So, let’s get started and make pagination a breeze!

Understanding the Challenge

So, you've inherited a codebase that's supposed to handle pagination using the Criteria API, but there's a catch: the Pageable parameter is showing up as unused. This is a common scenario, and it usually means the pagination logic isn't fully implemented. The goal here is to efficiently retrieve data in chunks, improving performance and user experience, especially when dealing with large datasets. Manual pagination gives you precise control over how data is fetched, which can be a game-changer for complex applications. Without proper pagination, your application might load all data at once, leading to slow response times and a poor user experience. Imagine having thousands of records and trying to display them all on a single page – that’s a recipe for disaster!

To tackle this, we need to understand how the Criteria API works with pagination. The Criteria API allows you to build queries programmatically, which is super useful for dynamic and complex queries. However, implementing pagination manually requires a bit more effort. We need to set the starting point (the offset) and the number of records to fetch (the limit) in our query. This involves using methods like setFirstResult() and setMaxResults() provided by the JPA TypedQuery. So, the challenge is to integrate these methods with the Pageable object, which Spring Data JPA provides for handling pagination information.

Furthermore, consider the database implications. Fetching all records and then paginating in memory is highly inefficient. We want the database to do the heavy lifting by using the LIMIT and OFFSET clauses in the SQL query. This reduces the amount of data transferred and processed by the application server, leading to significant performance gains. Therefore, our implementation must ensure that the pagination parameters are correctly translated into the SQL query. We also need to handle edge cases, such as invalid page numbers or page sizes, to prevent unexpected behavior and ensure a smooth user experience.

Diving into the Code: A Step-by-Step Implementation

Let's get our hands dirty with some code. Suppose you have a method that's supposed to fetch a paginated list of entities using the Criteria API. Here’s a typical scenario:

public List<YourEntity> findPaginated(Pageable pageable) {
    // Implementation goes here
}

The Pageable interface provides information about the page number and page size. However, as the problem states, the pageable parameter is marked as unused. So, how do we hook it up? First, we need to create a CriteriaBuilder and a CriteriaQuery. These are the core components for building our query programmatically. The CriteriaBuilder is used to create query elements, such as predicates and ordering, while the CriteriaQuery defines the structure of the query itself.

EntityManager em = entityManagerFactory.createEntityManager();
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<YourEntity> cq = cb.createQuery(YourEntity.class);
Root<YourEntity> root = cq.from(YourEntity.class);
cq.select(root);

Now comes the crucial part: applying the pagination parameters. We need to create a TypedQuery from our CriteriaQuery and then set the first result and max results based on the Pageable object. The Pageable interface provides methods like getPageNumber() and getPageSize() which we can use to calculate the offset. Remember that page numbers are usually zero-indexed, so the first page is 0, the second page is 1, and so on. The offset is calculated by multiplying the page number by the page size.

TypedQuery<YourEntity> typedQuery = em.createQuery(cq);
typedQuery.setFirstResult(pageable.getPageNumber() * pageable.getPageSize());
typedQuery.setMaxResults(pageable.getPageSize());
List<YourEntity> resultList = typedQuery.getResultList();

By setting setFirstResult() and setMaxResults(), we instruct the database to return only the records within the specified range. This is the key to efficient manual pagination. Finally, remember to close the EntityManager to release resources. Putting it all together, the method might look something like this:

import org.springframework.data.domain.Pageable;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.TypedQuery;
import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Root;
import java.util.List;

public class YourRepository {

    private final EntityManagerFactory entityManagerFactory;

    public YourRepository(EntityManagerFactory entityManagerFactory) {
        this.entityManagerFactory = entityManagerFactory;
    }

    public List<YourEntity> findPaginated(Pageable pageable) {
        EntityManager em = entityManagerFactory.createEntityManager();
        CriteriaBuilder cb = em.getCriteriaBuilder();
        CriteriaQuery<YourEntity> cq = cb.createQuery(YourEntity.class);
        Root<YourEntity> root = cq.from(YourEntity.class);
        cq.select(root);

        TypedQuery<YourEntity> typedQuery = em.createQuery(cq);
        typedQuery.setFirstResult(pageable.getPageNumber() * pageable.getPageSize());
        typedQuery.setMaxResults(pageable.getPageSize());

        List<YourEntity> resultList = typedQuery.getResultList();
        em.close();
        return resultList;
    }
}

Handling Sorting and Filtering

Pagination isn't the only concern; we often need to sort and filter data as well. The Criteria API shines here because it allows us to add sorting and filtering conditions dynamically. Let’s say you want to sort the results by a specific field. You can use the orderBy() method of the CriteriaQuery to achieve this. The Sort object from the Pageable interface provides the sorting information.

import org.springframework.data.domain.Sort;
import javax.persistence.criteria.Order;

// Inside the findPaginated method
if (pageable.getSort() != null) {
    for (Sort.Order order : pageable.getSort()) {
        Order sortOrder = order.isAscending() ? cb.asc(root.get(order.getProperty())) : cb.desc(root.get(order.getProperty()));
        cq.orderBy(sortOrder);
    }
}

This snippet iterates through the sorting orders specified in the Pageable object and adds them to the CriteriaQuery. We check if the order is ascending or descending and create the appropriate Order object using cb.asc() or cb.desc(). This gives you the flexibility to sort by multiple fields and directions.

Filtering is another common requirement. Suppose you want to filter results based on certain criteria, such as a date range or a specific status. You can add predicates to the CriteriaQuery using the where() method. For example, if you want to filter entities with a status of “Active,” you can do something like this:

import javax.persistence.criteria.Predicate;

// Inside the findPaginated method
Predicate statusPredicate = cb.equal(root.get("status"), "Active");
cq.where(statusPredicate);

You can combine multiple predicates using cb.and() or cb.or() to create complex filtering conditions. The key is to build these predicates dynamically based on the request parameters. This allows you to create flexible and powerful search capabilities. Remember to handle potential null values and edge cases in your filtering logic to avoid unexpected results.

Calculating Total Count for Pagination

Pagination is incomplete without knowing the total number of records. This information is essential for displaying the correct number of pages and navigation controls. To get the total count, we need to execute a separate query that counts the total number of entities matching the criteria. This can be done using the same CriteriaBuilder and predicates, but with a different CriteriaQuery.

public long countTotal(CriteriaQuery<?> cq) {
    EntityManager em = entityManagerFactory.createEntityManager();
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<Long> countQuery = cb.createQuery(Long.class);
    countQuery.select(cb.count(countQuery.from(cq.getResultType())));
    countQuery.where(cq.getRestriction());
    long count = em.createQuery(countQuery).getSingleResult();
em.close();
    return count;
}

This method creates a new CriteriaQuery that counts the entities. We reuse the predicates from the original query to ensure we're counting only the records that match the filtering criteria. This is crucial for accurate pagination. After getting the total count, you can create a Page object using the Pageable information and the total count. The Page object is a Spring Data JPA construct that represents a paginated result.

import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageImpl;

// After getting the resultList and totalCount
long totalCount = countTotal(cq);
Page<YourEntity> page = new PageImpl<>(resultList, pageable, totalCount);
return page;

The PageImpl constructor takes the list of results, the Pageable object, and the total count as parameters. This Page object can then be returned to the client, providing all the necessary information for pagination. Remember to handle cases where no records match the criteria, which can result in an empty page. Proper error handling and edge case management are essential for a robust pagination implementation.

Best Practices and Optimization Tips

Implementing manual pagination with the Criteria API can be powerful, but it's crucial to follow best practices to ensure optimal performance and maintainability. Here are some tips to keep in mind:

Use Indexes: Ensure that the columns you're sorting and filtering on are indexed in your database. Indexes can significantly speed up query performance, especially for large datasets. Without proper indexing, your queries might perform full table scans, which can be very slow.
**Avoid Select ***: When fetching data for pagination, only select the columns you need. Fetching unnecessary columns can increase the amount of data transferred and processed, slowing down your application. Use projections in your Criteria API queries to select only the required fields.
Cache Total Count: Calculating the total count can be expensive, especially for complex queries. If the data doesn't change frequently, consider caching the total count to avoid repeated queries. Caching can significantly reduce the load on your database and improve response times.
Use Connection Pooling: Connection pooling can help reduce the overhead of establishing database connections. Spring Boot typically configures connection pooling by default, but ensure it's properly configured for your environment.
Profile Your Queries: Use database profiling tools to analyze your queries and identify performance bottlenecks. Profiling can help you understand how your queries are executed and where you can make improvements. Tools like the Spring Boot Actuator can provide valuable insights into your application's performance.
Handle Edge Cases: Always handle edge cases, such as invalid page numbers or page sizes. Return appropriate error responses to the client to avoid unexpected behavior. Input validation is crucial for preventing issues and ensuring a smooth user experience.
Keep Queries Simple: While the Criteria API allows for complex queries, try to keep your queries as simple as possible. Complex queries can be harder to optimize and may lead to performance issues. Break down complex queries into smaller, more manageable parts if necessary.

Conclusion

So, there you have it! Implementing manual pagination in Spring Boot with the Criteria API might seem daunting at first, but with a clear understanding of the concepts and the right approach, it becomes manageable. We've covered the basics, delved into the code, and explored best practices. Remember, pagination is not just about splitting data into pages; it’s about creating a smooth and efficient user experience. By leveraging the power of the Criteria API and following the tips we've discussed, you can build robust and scalable pagination solutions. Keep practicing, keep experimenting, and you’ll become a pagination pro in no time! Happy coding, guys!