SpringbootHow-ToBeginner · 4 min read

How to Use Derived Query Method in Spring Boot

In Spring Boot, you use derived query methods by defining method names in your repository interface that follow naming conventions reflecting the query you want. Spring Data JPA automatically generates the query based on the method name, so you don't need to write SQL or JPQL manually.

📐

Syntax

A derived query method is defined in a Spring Data repository interface by naming the method to describe the query. The method name starts with keywords like findBy, getBy, or readBy, followed by the entity's field names combined with conditions like And, Or, and operators like Between, LessThan, etc.

Spring parses the method name and creates the query automatically.

java

public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByLastName(String lastName);
    List<User> findByAgeGreaterThan(int age);
    Optional<User> findByEmailAndStatus(String email, String status);
}

💻

Example

This example shows a Spring Boot repository interface with derived query methods to find users by last name, age greater than a value, and by email and status together.

java

import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;
import java.util.Optional;
import org.springframework.stereotype.Service;

public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByLastName(String lastName);
    List<User> findByAgeGreaterThan(int age);
    Optional<User> findByEmailAndStatus(String email, String status);
}

// Usage in a service class
@Service
public class UserService {
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public void demoQueries() {
        List<User> smiths = userRepository.findByLastName("Smith");
        List<User> adults = userRepository.findByAgeGreaterThan(18);
        Optional<User> activeUser = userRepository.findByEmailAndStatus("user@example.com", "ACTIVE");

        System.out.println("Users with last name Smith: " + smiths.size());
        System.out.println("Users older than 18: " + adults.size());
        System.out.println("Active user found: " + activeUser.isPresent());
    }
}

Output

Users with last name Smith: 3 Users older than 18: 10 Active user found: true

⚠️

Common Pitfalls

Incorrect method names: If the method name does not follow Spring Data conventions, it will cause runtime errors.
Unsupported keywords: Using unsupported keywords or misspelling field names will break query generation.
Complex queries: Derived queries are limited to simple conditions; complex joins or aggregations require @Query annotations.

java

public interface UserRepository extends JpaRepository<User, Long> {
    // Wrong: 'findByLastname' should be 'findByLastName' (case sensitive)
    List<User> findByLastname(String lastName); // This will fail

    // Correct:
    List<User> findByLastName(String lastName);
}

📊

Quick Reference

Here are some common keywords for derived query methods:

Keyword	Meaning / Usage
findBy	Start of query method to find entities by condition
And	Combine multiple conditions with AND
Or	Combine multiple conditions with OR
Between	Find values between two values
LessThan	Find values less than given value
GreaterThan	Find values greater than given value
IsNull	Find where field is null
Like	Find using SQL LIKE pattern
OrderBy	Sort results by field

✅

Key Takeaways

Define repository methods with names that describe the query using Spring Data conventions.

Spring Boot automatically generates queries from these method names, no SQL needed.

Use simple keywords like findBy, And, Or, GreaterThan to build queries.

Check method names carefully for correct field names and casing to avoid errors.

For complex queries, use @Query annotation instead of derived methods.