Spring Boot @IdClass Example

1. Introduction

In this blog post, we will explore how to use the @IdClass annotation to create a composite primary key for an entity in a Spring Boot application.

Key Points:

1. @IdClass is used to specify a composite primary key for an entity.

2. It separates the composite key definition from the entity and references a separate primary key class.

3. The @IdClass annotation is placed on the entity class, and the associated primary key class is defined with fields that correspond to the combined keys.

4. Each field in the primary key class must have the same name and type as the primary key fields in the entity.

5. Using @IdClass simplifies working with composite keys without embedding the key class itself within the entity class.

2. Implementation Steps

1. Define a primary key class that represents the composite key.

2. Annotate the primary key fields within the entity class with @Id.

3. Annotate the entity class with @IdClass, referencing the primary key class.

4. Implement the primary key class with equals() and hashCode() methods.

5. Use the entity in your repository as you would with any other entity.

3. Implementation Example

// Step 1: Create a primary key class
public class OrderId implements Serializable {
    private Long customerId;
    private Long orderId;

    // Constructors, getters, setters, equals(), and hashCode() methods

// Step 2: Annotate the entity class with @Id and @IdClass
public class Order {
    private Long customerId;

    private Long orderId;

    private String orderDetails;

    // Standard getters and setters

// Step 3: Implement a repository interface for the entity
public interface OrderRepository extends JpaRepository<Order, OrderId> {

// Step 4: Use the repository in a service class
public class OrderService {
    private final OrderRepository orderRepository;

    public OrderService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;

    // Business logic to handle orders

// Step 5: Optionally, create a REST controller to manage orders
public class OrderController {
    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;

    // Endpoints to handle HTTP requests for orders

// Step 6: Run the application
public class IdClassExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(IdClassExampleApplication.class, args);

// When you create or retrieve an Order, both customerId and orderId will be used as the composite primary key.


1. OrderId: This class represents the composite primary key for the Order entity.

2. Serializable: The OrderId class implements Serializable as required for primary key classes.

3. @Entity: Marks the Order class as a JPA entity.

4. @Id: Used to mark customerId and orderId as the composite primary keys in the Order entity.

5. @IdClass(OrderId.class): Specifies that the OrderId class will be used as the primary key class for the Order entity.

6. OrderRepository: Extends JpaRepository, allowing for CRUD operations on Order entities using the composite key.

7. OrderService: A service layer bean that uses OrderRepository to perform business operations.

8. @Service: Indicates that OrderService is a Spring-managed service bean.

9. OrderController: A REST controller that provides endpoints for managing Order entities.

10. @RestController and @RequestMapping: Used to create RESTful endpoints.

11. IdClassExampleApplication: The main application class that enables auto-configuration and component scanning.

12. SpringApplication.run(): Boots up the Spring Boot application, which in turn creates the JPA entity manager and handles the entity lifecycle.