Custom Queries with Spring Data JPA

byTech Blogger •April 16, 2025

0

Custom Queries with Spring Data JPA: The Power of @Query Annotation

Introduction

As a developer, you’re often faced with the challenge of retrieving specific data from your database efficiently. While Spring Data JPA provides powerful features for automating the creation of basic CRUD (Create, Read, Update, Delete) queries, sometimes you need more control over the exact query being sent to your database. This is where the @Query annotation comes in handy! In this blog post, we will explore how to use the @Query annotation to write custom queries in Spring Data JPA, allowing you to perform complex database operations with ease.

Usages

The @Query annotation in Spring Data JPA can be incredibly flexible and is used for several purposes:

Custom Queries: You can define your own JPQL (Java Persistence Query Language) or SQL queries directly within your repository interfaces.
Dynamic Parameters: Easily bind parameters to your queries without worrying about string concatenation or manual parsing.
Complex Joins: Handle complex relationships and joins effortlessly, giving you better control over how data is queried.
Native Queries: Execute native SQL queries directly, allowing you to tap into database features that might not be represented in JPQL.
Readability: Custom queries can enhance the readability of your code by making your data retrieval intentions explicit.

Code Example

Let’s dive into a simple example that showcases how to use the @Query annotation to create custom queries.

Step 1: Define Your Entity Class

Assuming we have an entity called Customer, here’s what the class could look like:

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Customer {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;
    private int age;

    // Getters and Setters
}

Step 2: Create the Custom Query in the Repository

Now, let’s create the repository interface and add custom queries using the @Query annotation:

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.stereotype.Repository;

import java.util.List;

@Repository
public interface CustomerRepository extends JpaRepository<Customer, Long> {

    // Custom JPQL Query to find customers by name
    @Query("SELECT c FROM Customer c WHERE c.name = ?1")
    List<Customer> findByName(String name);

    // Custom SQL Query to find customers older than a specific age
    @Query(value = "SELECT * FROM customers WHERE age > ?1", nativeQuery = true)
    List<Customer> findOlderThan(int age);
}

Step 3: Using the Custom Queries in a Service

Here's how you would utilize these custom queries in a service class:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class CustomerService {

    @Autowired
    private CustomerRepository customerRepository;

    public List<Customer> getCustomersByName(String name) {
        return customerRepository.findByName(name);
    }

    public List<Customer> getCustomersOlderThan(int age) {
        return customerRepository.findOlderThan(age);
    }
}

Explanation

Let’s break down this example to understand how the @Query annotation enhances our data retrieval capabilities:

Customer Entity: This basic entity represents a customer and reflects a table in the database.
CustomerRepository Interface: This interface extends JpaRepository, enabling built-in methods for basic operations. The custom methods findByName and findOlderThan use the @Query annotation to define specific queries:
- findByName(String name): This method retrieves customers whose names match the provided parameter using a JPQL query.
- findOlderThan(int age): This method retrieves customers older than a certain age using a native SQL query.
CustomerService Class: This service class incorporates the repository and provides methods that utilize the custom queries. It simply calls the repository methods and facilitates business logic around them.

Best Practices

To make the most of the @Query annotation in your Spring Data JPA projects, consider the following best practices:

Parameter Binding: Always use parameter binding (like ?1, :name) instead of concatenating strings to prevent SQL injection attacks and ensure safer queries.
Readability and Maintainability: When writing complex queries, aim for clarity. JPQL is often more expressive, making your queries easier to read compared to raw SQL.
Avoid Complex Queries: Keep your queries as simple as possible. If you find yourself writing overly complex queries, consider whether that logic would be better handled in Java rather than in the database.
Utilize Named Queries: For queries that you will use frequently, consider defining named queries using the @NamedQuery annotation within your entity to improve performance.
Testing: Ensure your custom queries are covered by unit tests to verify their correctness and efficiency under various conditions.

Conclusion

The @Query annotation in Spring Data JPA empowers developers to write custom queries tailored to specific use cases, allowing for efficient and precise data retrieval. Whether you're looking to execute simple lookups or complex operations, mastering this powerful tool can significantly enhance your application's data layer. With the flexibility to use both JPQL and native SQL, you can ensure that your database access is both effective and optimized for performance.

Now that you’ve learned about the power of custom queries with the @Query annotation, you can harness this capability to make your Spring Data JPA projects more robust and efficient.

Tags: spring data jpa