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.

Writing Queries with Micronaut Data: Finder Methods

🔎 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<Student> 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<Student> findByName(String name);

Generated Query:

SELECT * FROM students WHERE name = ?

2️⃣ Find by Email

Optional<Student> 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<Student> findByNameAndEmail(String name, String email);

Generated Query :

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

4️⃣ Find Students Born After a Date

List<Student> 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<Student> 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<Student> findByNameLike(String namePattern);

Pass %pattern% to match substrings.

studentRepository.findByNameLike("%John%");

Generated Query:

1 2	SELECT * FROM students WHERE name LIKE ?

🔥 Using Sorting with Finder Methods

Micronaut allows sorting results automatically.

Sort by Name Ascending

List<Student> findByEmailOrderByNameAsc(String email);

Generated Query:

1 2	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<Student, Long> {

List<Student> findByName(String name);

Optional<Student> findByEmail(String email);

Optional<Student> findByNameAndEmail(String name, String email);

List<Student> findByDateOfBirthAfter(LocalDate date);

List<Student> findByNameLike(String namePattern);

List<Student> findByNameIlike(String name);

List<Student> findByEmailOrderByNameAsc(String email);

}

🚀 Advantages of Finder Methods

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

🐞 Common Errors

Error	Cause	Solution
`No property found`	Invalid method name	Match exact field names
`Cannot resolve repository`	Bean not found	Check package scanning
Query returns wrong data	Method name logic incorrect	Review field names and operators

📚 Supported Keywords

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

Keyword	Description
`And` / `Or`	Combine conditions
`Between`	Range search
`LessThan`, `GreaterThan`	Comparisons
`Like` / `Ilike`	Wildcard matching
`IsNull` / `IsNotNull`	Null checks
`In`	Search in a list
`OrderBy`	Sorting results

✅ 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.