Writing Queries with Micronaut Data: Finder Methods

One of the most powerful features of Micronaut Data is its ability to generate database queries at compile-time just by analyzing method names. This approach is called Finder Methods or Derived Queries.

👉 You don’t need to write SQL for common queries.
👉 You don’t need to write any custom implementation.
👉 Micronaut will do the heavy lifting for you — safely and efficiently.

🔎 What are Finder Methods?

Finder Methods are special method names you define inside your repository interface.
Micronaut parses these names and automatically generates SQL queries for them at compile-time.

For example:

List findByName(String name);

👉 Micronaut will automatically generate:

SELECT * FROM students WHERE name = ?

⚙ How Finder Methods Work

Micronaut Data uses naming conventions to determine:

• Which field(s) to query.
• What operation to apply (equals, greater than, like, etc).
• Whether it’s a single record or list.
• Whether sorting or pagination is needed.

🏫 Sample Entity: Student

Let’s continue using the same entity from our previous post – Defining Entities and Repositories in Micronaut:

package com.kscodes.micronaut.school.entities;

import io.micronaut.data.annotation.*;

import java.time.LocalDate;

@MappedEntity("students")
public class Student {
    @Id
    @GeneratedValue(GeneratedValue.Type.IDENTITY)
    private Long id;
    private String name;
    private LocalDate dateOfBirth;
    private String email;

    // Getters and Setters
}

🔧 Creating Finder Methods

1️⃣ Find by Name

List findByName(String name);

Generated Query:

SELECT * FROM students WHERE name = ?

2️⃣ Find by Email

Optional findByEmail(String email);

Generated Query:

SELECT * FROM students WHERE email = ?

Use Optional<T> for single results (helps avoid nulls).

3️⃣ Find by Name and Email

Optional findByNameAndEmail(String name, String email);

Generated Query :

SELECT * FROM students WHERE name = ? AND email = ?

4️⃣ Find Students Born After a Date

List findByDateOfBirthAfter(LocalDate date);

Generated Query:

SELECT * FROM students WHERE date_of_birth > ?

✅ Supports comparison operators: After, Before, GreaterThan, LessThan, etc.

5️⃣ Case Insensitive Search

List findByNameIlike(String name);

Ilike does a case-insensitive search.

Generated Query:

SELECT * FROM students WHERE LOWER(name) LIKE LOWER(?)

6️⃣ Partial Match with Like

List findByNameLike(String namePattern);

Pass %pattern% to match substrings.

studentRepository.findByNameLike("%John%");

Generated Query:

SELECT * FROM students WHERE name LIKE ?

🔥 Using Sorting with Finder Methods

Micronaut allows sorting results automatically.

Sort by Name Ascending

List findByEmailOrderByNameAsc(String email);

Generated Query:

SELECT * FROM students WHERE email = ? ORDER BY name ASC

📄 Full Repository Example

package com.kscodes.micronaut.school.repositories;
import com.kscodes.micronaut.school.entities.Student;
import io.micronaut.data.annotation.Repository;
import io.micronaut.data.repository.CrudRepository;
import java.time.LocalDate;
import java.util.List;
import java.util.Optional;
@Repository
public interface StudentRepository extends CrudRepository {
    List findByName(String name);
    Optional findByEmail(String email);
    Optional findByNameAndEmail(String name, String email);
    List findByDateOfBirthAfter(LocalDate date);
    List findByNameLike(String namePattern);
    List findByNameIlike(String name);
    List findByEmailOrderByNameAsc(String email);
}

🚀 Advantages of Finder Methods

✅ No boilerplate code
✅ Compile-time validation
✅ Type-safe queries
✅ No runtime query errors
✅ Faster development

🐞 Common Errors

📚 Supported Keywords

Here are some of the keywords Micronaut Data supports in Finder Methods:

✅ Full list available in Micronaut Data Docs – Query Methods

✅ Summary

• We learned how to write Finder Methods in Micronaut Data.
• Finder Methods reduce boilerplate and increase productivity.
• Queries are validated at compile time.
• You can easily build complex queries without SQL.