Spring Boot 4 Complete Guide · Lesson

Derived Query Methods and Keyword Resolution

Build complex repository queries purely from method names using Spring Data's property-keyword grammar.

Derived Query Methods and Keyword Resolution is a free Spring Boot 4 Complete Guide lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Complete Guide learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Are Derived Query Methods?

Spring Data JPA can generate a full SQL query just by reading the name of a repository method. You write the method signature, leave the body to the framework, and Spring parses the name into a query at startup.

No @Query annotation needed
No hand-written JPQL or SQL
The method name is the query specification

This is called a derived query method, because the query is derived from the method name.

public interface UserRepository extends JpaRepository<User, Long> {

    // Spring derives: SELECT u FROM User u WHERE u.email = ?1
    User findByEmail(String email);
}

The Subject and the Predicate

Every derived method name splits into two parts:

The subject (an introducer like findBy, readBy, queryBy, getBy) which tells Spring what action to perform.
The predicate (everything after By) which becomes the WHERE clause.

In findByLastName, find is the subject and LastName is the predicate that maps to the lastName entity property.

public interface CustomerRepository extends JpaRepository<Customer, Long> {

    List<Customer> findByLastName(String lastName);

    List<Customer> readByCity(String city);  // 'readBy' works too

    Customer getById(Long id);               // 'getBy' works too
}

Combining Conditions with And / Or

You chain multiple properties using the keywords And and Or. Each property name in the chain must match an entity field, and the method parameters are bound left-to-right in the same order they appear.

findByFirstNameAndLastName → WHERE first_name = ?1 AND last_name = ?2
findByCityOrCountry → WHERE city = ?1 OR country = ?2

public interface CustomerRepository extends JpaRepository<Customer, Long> {

    List<Customer> findByFirstNameAndLastName(String firstName, String lastName);

    List<Customer> findByCityOrCountry(String city, String country);
}

Comparison Keywords

Beyond equality, Spring Data understands a rich set of comparison keywords appended after the property name:

LessThan, LessThanEqual, GreaterThan, GreaterThanEqual
Between — needs two parameters
Before, After — handy for dates

The keyword binds to the property right before it, so findByAgeGreaterThan targets the age property.

public interface ProductRepository extends JpaRepository<Product, Long> {

    List<Product> findByPriceLessThan(BigDecimal max);

    List<Product> findByPriceBetween(BigDecimal low, BigDecimal high);

    List<Product> findByCreatedAtAfter(LocalDateTime since);
}

Null, True, and Boolean Keywords

Some keywords take no parameter at all because the condition is baked into the name:

IsNull / IsNotNull → IS NULL / IS NOT NULL
True / False → compares a boolean property to true/false

Notice that findByActiveTrue() has an empty parameter list — the value is fixed by the keyword.

public interface AccountRepository extends JpaRepository<Account, Long> {

    List<Account> findByDeletedAtIsNull();

    List<Account> findByActiveTrue();

    List<Account> findByActiveFalse();
}

String Matching Keywords

For text columns, Spring Data offers keywords that translate into LIKE patterns:

Like — you supply the wildcards (%) yourself
StartingWith — appends % automatically
EndingWith — prepends %
Containing — wraps the value in %value%
IgnoreCase — makes the comparison case-insensitive

public interface CustomerRepository extends JpaRepository<Customer, Long> {

    List<Customer> findByEmailContaining(String fragment);

    List<Customer> findByLastNameStartingWith(String prefix);

    List<Customer> findByLastNameIgnoreCase(String lastName);
}

Ordering Results with OrderBy

You can embed sorting directly in the method name using OrderBy followed by the property and a direction (Asc or Desc). It goes at the very end of the predicate.

findByLastNameOrderByFirstNameAsc
findByActiveTrueOrderByCreatedAtDesc

For dynamic sorting at call time, prefer passing a Sort parameter instead of hard-coding it in the name.

public interface CustomerRepository extends JpaRepository<Customer, Long> {

    List<Customer> findByLastNameOrderByFirstNameAsc(String lastName);

    // Dynamic sort, supplied by the caller
    List<Customer> findByCity(String city, Sort sort);
}

Limiting with First and Top

To restrict how many rows come back, add First or Top right after the subject. They are interchangeable, and an optional number sets the limit.

findFirstByOrderByCreatedAtDesc → the single newest row
findTop3ByCategory → at most 3 rows for that category

Combined with OrderBy this is the idiomatic way to fetch "the latest N" records.

public interface OrderRepository extends JpaRepository<Order, Long> {

    Order findFirstByCustomerIdOrderByPlacedAtDesc(Long customerId);

    List<Order> findTop5ByStatusOrderByPlacedAtDesc(String status);
}

Traversing Nested Properties

Derived queries can reach into related entities. If Order has a Customer and the customer has an address.city, you can write findByCustomerAddressCity.

Spring resolves the path greedily, splitting on camel-case humps. When a property name is itself ambiguous (e.g. a field literally named customerAddress), insert an underscore to make the boundary explicit: findByCustomer_AddressCity.

public interface OrderRepository extends JpaRepository<Order, Long> {

    // Order -> customer -> address -> city
    List<Order> findByCustomerAddressCity(String city);

    // Explicit traversal boundary with underscore
    List<Order> findByCustomer_AddressCity(String city);
}

Counting, Existence, and Deletion

The subject keyword controls the operation, not just selection. Beyond find, you can derive:

countBy... → returns a long
existsBy... → returns a boolean
deleteBy... / removeBy... → deletes matching rows (use with @Transactional)

The predicate grammar is identical; only the return type and the action change.

public interface UserRepository extends JpaRepository<User, Long> {

    long countByActiveTrue();

    boolean existsByEmail(String email);

    @Transactional
    long deleteByLastLoginBefore(LocalDateTime cutoff);
}

How Keyword Resolution Actually Works

At application startup, Spring Data parses each method name into a PartTree. For every segment it tries the longest matching property path first, then peels off trailing keywords.

It validates each property against the entity's metamodel — a typo like findByemaill fails fast with PropertyReferenceException.
Because parsing happens at startup, broken method names break the context immediately, not at first call.

This pure-Java example shows the same camel-case splitting idea the parser uses.

public class PartTreeDemo {
    public static void main(String[] args) {
        String predicate = "FirstNameAndLastName";
        String[] parts = predicate.split("And");
        for (String p : parts) {
            // Lower-case the first letter to get the property name
            String prop = Character.toLowerCase(p.charAt(0)) + p.substring(1);
            System.out.println("Property: " + prop);
        }
    }
}

Quick Check

You need a repository method that returns the 3 most recently placed orders for a given status, newest first. Which derived method name is correct?

Recap

You now know how to build queries straight from method names:

Subject (find/read/get/count/exists/delete) sets the operation; predicate after By becomes the WHERE clause.
Combine fields with And/Or; compare with LessThan, Between, After; match text with Containing, StartingWith, IgnoreCase.
Parameter-free keywords: IsNull, True, False.
Sort with OrderBy...Asc/Desc (or a Sort param); limit with First/Top[N].
Traverse relations (findByCustomerAddressCity, use _ to disambiguate).
Spring parses names into a PartTree at startup, so invalid property paths fail fast.

For very long or complex names, switch to @Query — readability beats cleverness.

Frequently asked questions

Is the “Derived Query Methods and Keyword Resolution” lesson free?

Yes — the full text of “Derived Query Methods and Keyword Resolution” is free to read here on the web, and the Spring Boot 4 Complete Guide course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Complete Guide course, upgrade to CoddyKit PRO.

What will I learn in “Derived Query Methods and Keyword Resolution”?

Build complex repository queries purely from method names using Spring Data's property-keyword grammar. You practise Spring Boot 4 Complete Guide with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Complete Guide?

No prior experience is required. Spring Boot 4 Complete Guide on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Derived Query Methods and Keyword Resolution” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Complete Guide lesson?

Yes. Every Spring Boot 4 Complete Guide lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Derived Query Methods and Keyword Resolution
JPQL and Native Queries with @Query
Specifications and Criteria-Based Dynamic Filtering
Pagination, Sorting, and Slice Streaming

← Back to Spring Boot 4 Complete Guide