Spring Data JPA Specification Example

The Specification mechanism in Spring Data JPA provides a way to write criteria queries in a type-safe and programmatic way. It's particularly useful for constructing dynamic queries based on various conditions.

Here's a step-by-step guide to get you started with Spring Data JPA Specifications:

1. Setting up the project

Make sure you have the required dependencies. In your pom.xml, you should have:


2. Define your Entity

For demonstration, let's consider an entity Book:

public class Book {
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private String author;
    private LocalDate publishDate;

    // getters, setters, etc.

3. Create a Repository

Your repository should extend JpaSpecificationExecutor to support Specifications:

public interface BookRepository extends JpaRepository<Book, Long>, JpaSpecificationExecutor<Book> {

4. Define Specifications

The Specification interface has a single method toPredicate which you can implement to define the criteria. Let's create a utility class BookSpecifications to define our specifications:

public class BookSpecifications {
    public static Specification<Book> hasTitle(String title) {
        return (root, query, criteriaBuilder) -> criteriaBuilder.like(root.get("title"), "%" + title + "%");

    public static Specification<Book> hasAuthor(String author) {
        return (root, query, criteriaBuilder) -> criteriaBuilder.equal(root.get("author"), author);

    public static Specification<Book> publishedAfter(LocalDate date) {
        return (root, query, criteriaBuilder) -> criteriaBuilder.greaterThan(root.get("publishDate"), date);

5. Using Specifications to Query Data in Service Class

You can now leverage the defined specifications to query data dynamically:

public class BookService {

    private BookRepository bookRepository;

    public List<Book> findBooks(String title, String author, LocalDate date) {
        return bookRepository.findAll(

This service method will allow you to:

  • Find books by title (passing title and null for other parameters). 
  • Find books by author. 
  • Find books published after a certain date. 
Combine any of the above conditions.

6. Testing the Specifications

Now, let's test the specifications. You can create a unit test or use a controller to do this. Here's a sample test:

public class BookServiceTest {

    private BookService bookService;

    public void testSpecifications() {
        List<Book> booksByTitle = bookService.findBooks("Harry Potter", null, null);
        List<Book> booksByAuthor = bookService.findBooks(null, "J.K. Rowling", null);
        List<Book> booksAfterDate = bookService.findBooks(null, null, LocalDate.of(2000, 1, 1));

        // assert and validate the lists as per your needs


This is a basic example to get you started. Specifications can handle more complex scenarios, including relationships, joins, subqueries, and more. 

Using Specification is ideal for scenarios where queries need to be built dynamically based on user input or varying conditions. Always be cautious and validate input parameters to avoid potential security risks, especially if constructing queries based on user input.