Specification pattern for dynamic queries in Spring Boot

Introduction

The Specification pattern helps you build flexible and reusable database queries step-by-step without writing complex SQL. It makes filtering data easier and cleaner.

When you want to filter database results based on user input that can change often.

When you need to combine multiple search conditions dynamically.

When you want to keep your query logic clean and separated from your main code.

When you want to reuse query conditions in different parts of your app.

When you want to avoid writing many custom query methods for every filter combination.

Syntax

Spring Boot

public class YourEntitySpecification implements Specification<YourEntity> {
    private SearchCriteria criteria;

    public YourEntitySpecification(SearchCriteria criteria) {
        this.criteria = criteria;
    }

    @Override
    public Predicate toPredicate(Root<YourEntity> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
        switch (criteria.getOperation()) {
            case ">":
                return builder.greaterThan(root.get(criteria.getKey()), criteria.getValue().toString());
            case "<":
                return builder.lessThan(root.get(criteria.getKey()), criteria.getValue().toString());
            case ":":
                if (root.get(criteria.getKey()).getJavaType() == String.class) {
                    return builder.like(root.get(criteria.getKey()), "%" + criteria.getValue() + "%");
                } else {
                    return builder.equal(root.get(criteria.getKey()), criteria.getValue());
                }
            default:
                return null;
        }
    }
}

The Specification interface requires implementing the toPredicate method.

Use CriteriaBuilder to build conditions like equals, greater than, or like.

Examples

This example filters products by a string field using 'like' for partial matches.

Spring Boot

public class ProductSpecification implements Specification<Product> {
    private SearchCriteria criteria;

    public ProductSpecification(SearchCriteria criteria) {
        this.criteria = criteria;
    }

    @Override
    public Predicate toPredicate(Root<Product> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
        if (criteria.getOperation().equalsIgnoreCase(":")) {
            return builder.like(root.get(criteria.getKey()), "%" + criteria.getValue() + "%");
        }
        return null;
    }
}

This combines two conditions: price greater than 100 and category equals 'Books'.

Spring Boot

Specification<Product> spec = Specification.where(new ProductSpecification(new SearchCriteria("price", ">", 100)))
    .and(new ProductSpecification(new SearchCriteria("category", ":", "Books")));

Sample Program

This code defines a reusable specification for filtering products by name containing 'phone' and price greater than 500.

You can pass this specification to Spring Data JPA repository methods to get filtered results.

Spring Boot

import org.springframework.data.jpa.domain.Specification;
import jakarta.persistence.criteria.*;

public class SearchCriteria {
    private String key;
    private String operation;
    private Object value;

    public SearchCriteria(String key, String operation, Object value) {
        this.key = key;
        this.operation = operation;
        this.value = value;
    }

    public String getKey() { return key; }
    public String getOperation() { return operation; }
    public Object getValue() { return value; }
}

public class ProductSpecification implements Specification<Product> {
    private SearchCriteria criteria;

    public ProductSpecification(SearchCriteria criteria) {
        this.criteria = criteria;
    }

    @Override
    public Predicate toPredicate(Root<Product> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
        return switch (criteria.getOperation()) {
            case ">" -> builder.greaterThan(root.get(criteria.getKey()), criteria.getValue().toString());
            case "<" -> builder.lessThan(root.get(criteria.getKey()), criteria.getValue().toString());
            case ":" -> {
                if (root.get(criteria.getKey()).getJavaType() == String.class) {
                    yield builder.like(root.get(criteria.getKey()), "%" + criteria.getValue() + "%");
                } else {
                    yield builder.equal(root.get(criteria.getKey()), criteria.getValue());
                }
            }
            default -> null;
        };
    }
}

// Usage example in a service method
Specification<Product> spec = Specification.where(
    new ProductSpecification(new SearchCriteria("name", ":", "phone")))
    .and(new ProductSpecification(new SearchCriteria("price", ">", 500)));

// Then pass 'spec' to your repository method like findAll(spec)

Important Notes

Make sure your entity fields match the keys used in SearchCriteria.

You can combine multiple specifications with and and or for complex queries.

Use this pattern to keep your query logic clean and easy to maintain.

Summary

The Specification pattern helps build flexible database queries step-by-step.

It uses simple criteria objects to define conditions like equals, greater than, or contains.

You can combine multiple specifications to create complex filters easily.

Practice

1. What is the main purpose of the Specification pattern in Spring Boot?

easy

A. To manage application configuration properties

B. To create REST API endpoints automatically

C. To handle HTTP request routing

D. To build flexible and reusable database queries dynamically

Solution

1. Step 1: Understand the role of Specification pattern

   The Specification pattern is designed to help build database queries that can be combined and reused dynamically.

2. Step 2: Compare with other options

   Options A, C, and D relate to other Spring Boot features like configuration, routing, and REST APIs, not query building.

3. Final Answer:

   To build flexible and reusable database queries dynamically -> Option D

4. Quick Check:

   Specification pattern = flexible queries [OK]

Hint: Specification pattern builds flexible queries step-by-step [OK]

Common Mistakes:

• Confusing Specification with REST controller features
• Thinking it manages app configuration
• Assuming it handles HTTP routing

2. Which of the following is the correct method signature to implement in a Specification class in Spring Boot?

easy

A. public Predicate toPredicate(Root<T> root, CriteriaQuery query, CriteriaBuilder builder)

B. public void executeQuery(String sql)

C. public List<T> findAll()

D. public void configure()

Solution

1. Step 1: Recall Specification interface method

   The Specification interface requires implementing the toPredicate method with parameters Root, CriteriaQuery, and CriteriaBuilder.

2. Step 2: Eliminate incorrect options

   Options A, B, and C do not match the Specification interface method signature.

3. Final Answer:

   public Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuilder builder) -> Option A

4. Quick Check:

   Specification method = toPredicate(...) [OK]

Hint: Specification requires toPredicate method with root, query, builder [OK]

Common Mistakes:

• Using methods unrelated to Specification interface
• Missing correct method parameters
• Confusing with repository methods

3. Given the following Specification code snippet, what will be the result of the query?

Specification<User> spec = (root, query, builder) -> builder.equal(root.get("status"), "ACTIVE");
List<User> users = userRepository.findAll(spec);

medium

A. Throws a syntax error due to lambda usage

B. Returns all users regardless of status

C. Returns all users with status 'ACTIVE'

D. Returns users with status 'INACTIVE'

Solution

1. Step 1: Analyze the Specification lambda

   The lambda creates a predicate that filters users where the 'status' field equals 'ACTIVE'.

2. Step 2: Understand the repository call

   The findAll(spec) method applies this filter, returning only users matching the predicate.

3. Final Answer:

   Returns all users with status 'ACTIVE' -> Option C

4. Quick Check:

   Predicate filters status = ACTIVE [OK]

Hint: Predicate filters users by status 'ACTIVE' [OK]

Common Mistakes:

• Assuming it returns all users without filtering
• Thinking lambda causes syntax error
• Confusing status values

4. Identify the error in this Specification implementation:

public class UserSpec implements Specification<User> {
  public Predicate toPredicate(Root<User> root, CriteriaQuery query) {
    return builder.equal(root.get("age"), 30);
  }
}

medium

A. Missing CriteriaBuilder parameter in toPredicate method

B. Incorrect return type; should return boolean

C. Root parameter type is wrong

D. Method name should be buildPredicate

Solution

1. Step 1: Check toPredicate method signature

   The Specification interface requires three parameters: Root, CriteriaQuery, and CriteriaBuilder.

2. Step 2: Identify missing parameter

   The method is missing the CriteriaBuilder parameter, so it cannot build the predicate correctly.

3. Final Answer:

   Missing CriteriaBuilder parameter in toPredicate method -> Option A

4. Quick Check:

   toPredicate needs CriteriaBuilder parameter [OK]

Hint: toPredicate must have three parameters including CriteriaBuilder [OK]

Common Mistakes:

• Omitting CriteriaBuilder parameter
• Returning wrong type
• Wrong method name

5. How can you combine two Specifications spec1 and spec2 to create a dynamic query that matches records satisfying both conditions?

hard

A. Use spec1.or(spec2)

B. Use Specification.where(spec1).and(spec2)

C. Use spec1.add(spec2)

D. Use spec1.merge(spec2)

Solution

1. Step 1: Recall Specification combination methods

   Spring Data JPA Specification provides where(), and(), and or() methods to combine Specifications logically.

2. Step 2: Combine for AND condition

   To match records satisfying both conditions, use Specification.where(spec1).and(spec2).

3. Final Answer:

   Use Specification.where(spec1).and(spec2) -> Option B

4. Quick Check:

   Combine specs with where().and() for AND logic [OK]

Hint: Use where().and() to combine Specifications with AND logic [OK]

Common Mistakes:

• Using or() instead of and() for AND condition
• Using non-existent add() or merge() methods
• Not wrapping with Specification.where()