Spring Data JPA @Query Annotation with Example

Last Updated : 27 Mar, 2026

Spring Data JPA uses ORM (Object Relational Mapping) to map Java objects directly to database tables. It simplifies database operations, and when query methods are not sufficient, the @Query annotation is used to write custom and flexible queries for fetching data.

  • @Query Annotation supports both JPQL and native SQL queries.
  • It also supports SpEL expressions.
  • @Param in method arguments to bind query parameter.

Syntax of JPQL

@Query("SELECT * FROM Student ORDER BY age") Optional<Student> findSortedStudentByAge();

Syntax of Native

If you want to use this native query in the Spring Boot project then we have to take the help of @Query Annotation and we have to set an attribute nativeQuery=true in Query annotation to mark the query as native.

@Query(nativeQuery = true, value = "SELECT * FROM Student ORDER BY age") Optional<Student>

Example of Implementing

Step 1: Create Spring Boot Project

Create a Spring Boot project with the following configuration:

  • Project: Maven
  • Language: Java
  • Packaging: Jar
  • Java: 17

 Please choose the following dependencies while creating the project.

  • Spring Boot DevTools
  • Spring Data JPA
  • MySQL Driver
  • Spring Web

Generate the project and run it in IntelliJ IDEA by referring to the above article.

Step 2: Create Database and Tables

Go to your MySQL Workbench and create a schema named gfgmicroservicesdemo and inside that create a table called employee and address and put some sample data. 

Employee Table: Here we have created 4 columns and put some sample data.

  1. id
  2. name
  3. email
  4. age
 

Address Table: Here we have created 4 columns and put some sample data.

  1. id
  2. city
  3. state
  4. employee_id

Note: In the Address table, employee_id is a foreign key so create it accordingly. We are going to perform a SQL join operation in our native SQL query. So create tables carefully.

 

Before moving to IntelliJ IDEA let's have a look at the complete project structure for our Microservices.

 

Step 3: Configure application.properties

Now make the following changes in your application.properties file.

spring.datasource.url=jdbc:mysql://localhost:3306/gfgmicroservicesdemo
spring.datasource.username=put your username here
spring.datasource.password=put your password here
server.port=8081

 

Step 4: Create Your Entity/Model Class

Go to the src > main > java > entity and create a class Address and put the below code. This is our model class.

Java 
package com.gfg.addressapp.entity;

import jakarta.persistence.*;

@Entity
@Table(name = "address")
public class Address {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private int id;

    @Column(name = "city")
    private String city;

    @Column(name = "state")
    private String state;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }

    public String getState() {
        return state;
    }

    public void setState(String state) {
        this.state = state;
    }
}

Step 5: Create Your Repository Interface

  • Go to the src > main > java > repository and create an interface AddressRepo and put the below code.
  • This is our repository where we write code for all the database-related stuff.
Java 
package com.gfg.addressapp.repository;

import com.gfg.addressapp.entity.Address;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

@Repository
public interface AddressRepo extends JpaRepository<Address, Integer> {

    @Query(
        nativeQuery = true,
        value
        = "SELECT ea.id, ea.city, ea.state FROM gfgmicroservicesdemo.address ea join gfgmicroservicesdemo.employee e on e.id = ea.employee_id where ea.employee_id=:employeeId")
       Optional<Address> findAddressByEmployeeId(@Param("employeeId") int employeeId);
}

Here you can see we have used the native SQL query in the same way as we have discussed. This is our native SQL query

SELECT ea.id, ea.city, ea.state FROM gfgmicroservicesdemo.address ea join gfgmicroservicesdemo.employee e on e.id = ea.employee_id where ea.employee_id=:employeeId

And this is how we have used it in Spring Boot

@Query(nativeQuery = true, value = "SELECT ea.id, ea.city, ea.state FROM gfgmicroservicesdemo.address ea join gfgmicroservicesdemo.employee e on e.id = ea.employee_id where ea.employee_id=:employeeId")

 

Similarly, you can put your native SQL query according to your requirements in your Spring Boot project.

Note: Please refer to this article to know more about JpaRepository.

Step 6: Create an AddressResponse Class

Go to the src > main > java > response and create a class AddressResponse and put the below code.

Java 
package com.gfg.addressapp.response;

public class AddressResponse {

    private int id;
    private String city;
    private String state;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }

    public String getState() {
        return state;
    }

    public void setState(String state) {
        this.state = state;
    }
}

Step 7: Create Your Service Class

  • Go to the src > main > java > service and create a class AddressService and put the below code.
  • This is our service class where we write our business logic.
Java 
package com.gfg.addressapp.service;

import com.gfg.addressapp.entity.Address;
import com.gfg.addressapp.repository.AddressRepo;
import com.gfg.addressapp.response.AddressResponse;
import org.modelmapper.ModelMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Optional;

@Service
public class AddressService {

    @Autowired
    private AddressRepo addressRepo;

    @Autowired
    private ModelMapper mapper;

    public AddressResponse findAddressByEmployeeId(int employeeId) {
        Optional<Address> addressByEmployeeId = addressRepo.findAddressByEmployeeId(employeeId);
        AddressResponse addressResponse = mapper.map(addressByEmployeeId, AddressResponse.class);
        return addressResponse;
    }

}

Step 8: Create an Address Controller

  • The /address/{employeeId} endpoint is created in the controller to fetch address details based on the given employeeId.
  • A foreign key (employee_id) and a SQL JOIN in the native query are used to retrieve related data from both Employee and Address tables.
Java 
package com.gfg.addressapp.controller;

import com.gfg.addressapp.response.AddressResponse;
import com.gfg.addressapp.service.AddressService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AddressController {

    @Autowired
    private AddressService addressService;

    @GetMapping("/address/{employeeId}")
    public ResponseEntity<AddressResponse> getAddressByEmployeeId(@PathVariable("employeeId") int employeeId) {
        AddressResponse addressResponse = addressService.findAddressByEmployeeId(employeeId);
        return ResponseEntity.status(HttpStatus.OK).body(addressResponse);
    }

}

Step 9: Create a Configuration Class

Go to the src > main > java > configuration and create a class AddressConfig and put the below code.

Java 
package com.gfg.addressapp.configuration;

import com.gfg.addressapp.service.AddressService;
import org.modelmapper.ModelMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AddressConfig {

    @Bean
    public ModelMapper modelMapperBean() {
        return new ModelMapper();
    }

}

Step 10: Run Your Address Microservice

  • To run your Address Microservice src > main > java > AddressServiceApplication and click on the Run button.
  • If everything goes well then you may see the following screen in your console.

Step 11: Test Your Endpoint in Postman

Now open Postman and hit the following URL

GET: http://localhost:8081/address/2

And you can see the following response

{ "id": 1,
"city": "BLS",
"state": "Odisha"
}

Please refer to the below image.

Comment

Explore