DTO Projections in JPA

In real-world applications, fetching entire entities is often unnecessary and inefficient. Most use cases—such as REST APIs, dashboards, reports, and list views—require only a subset of fields.

Fetching full entities along with their relationships can lead to:

• Unnecessary data loading
• Higher memory usage
• Performance issues
• Lazy loading problems
• N+1 query issues

DTO Projections in Spring Data JPA solve this by allowing you to fetch only the required columns directly from the database and map them into DTOs (Data Transfer Objects).

---

What Is a DTO Projection?

A DTO Projection retrieves partial data from the database and maps it directly into:

• An interface
• A DTO class
• A record (Java 16+)

Instead of returning managed JPA entities, repository methods return DTOs.

---

Why DTO Projections Are Important

• Avoid fetching unnecessary entity fields
• Reduce memory consumption
• Improve query performance
• Prevent exposing internal entity structure in APIs
• Ideal for read-only use cases
• Helps avoid LazyInitializationException
• Cleaner API responses

? DTO projections are faster, safer, and cleaner than entities when updates are not required.

---

Types of DTO Projections in Spring Data JPA

Spring Data JPA supports three main projection types:

1. Interface-based Projections
2. Class-based (Constructor) Projections
3. Dynamic Projections

---

1. Interface-based Projection (Most Common)

Best for simple, read-only queries

Spring Data JPA automatically creates a proxy implementation and fetches only the fields declared in the interface.

Projection Interface

publicinterfaceUserSummary {
    LonggetId();
    StringgetName();
    StringgetEmail();
}

Repository

publicinterfaceUserRepositoryextendsJpaRepository<User, Long> {

    List<UserSummary>findByActiveTrue();
}

How It Works

• No JPQL required
• Spring generates optimized SELECT queries
• Only declared fields are fetched
• Excellent performance
• Clean and simple
• Not suitable for complex transformations

---

2. Class-based DTO Projection (Constructor Expression)

Best when custom logic or transformations are required

Uses JPQL’s new keyword to map query results into a DTO.

DTO Class

publicclassUserDTO {

private Long id;
private String name;
private String email;

publicUserDTO(Long id, String name, String email) {
this.id = id;
this.name = name;
this.email = email;
    }
}

Repository

@Query("""
    SELECT new com.example.dto.UserDTO(u.id, u.name, u.email)
    FROM User u
    WHERE u.active = true
""")
List<UserDTO>findActiveUsers();

Key Points

• Requires fully qualified DTO class name
• Constructor order must match query
• Explicit and flexible
• Best for complex mappings
• Requires JPQL

---

3. Dynamic Projections

Choose projection type at runtime

Useful when the same query must return different views of data.

Repository

publicinterfaceUserRepositoryextendsJpaRepository<User, Long> {

    <T> List<T>findByActiveTrue(Class<T> type);
}

Usage

List<UserSummary> summaries =
    userRepository.findByActiveTrue(UserSummary.class);

List<UserDTO> dtos =
    userRepository.findByActiveTrue(UserDTO.class);

• Highly flexible
• Reduces duplicate repository methods
• Slightly advanced

---

Nested (Closed) Projections

DTO projections can include nested objects using interfaces.

publicinterfaceOrderView {
    LonggetId();
    UserInfogetUser();

interfaceUserInfo {
        StringgetName();
        StringgetEmail();
    }
}

List<OrderView>findAll();

⚠️ Overusing nested projections may still trigger extra joins or queries.

---

DTO Projection vs Entity Fetching

Feature	DTO Projection	Entity Fetching
Data fetched	Only selected fields required for the use case are fetched from the database	The complete entity with all mapped fields is fetched
Performance	Faster because less data is retrieved and processed	Slower because the full entity is loaded
Memory usage	Lower memory consumption since only required fields are stored	Higher memory usage because full entities are kept in memory
Change tracking	Changes are not tracked because DTOs are not managed by JPA	Changes are tracked automatically by the JPA persistence context
Lazy loading	Lazy loading is not applicable because DTOs are not entities	Lazy loading is supported for entity relationships
N+1 query risk	Very low risk because data is fetched explicitly in queries	Possible if lazy associations are accessed without proper fetch strategy
Updates allowed	Read-only and should not be used for update operations	Supports create, update, and delete operations
Transaction requirement	Usually not required for simple read-only queries	Required, especially when using lazy-loaded associations
API safety	Safe for APIs because internal entity structure is hidden	Risky for APIs because entities may expose unwanted data
Best for APIs	Highly recommended for REST APIs and external clients	Not recommended for direct API exposure
Best use case	Read-only views, reports, dashboards, and API responses	Business logic, data manipulation, and persistence operations

Key Takeaway (Easy Rule)

DTO Projection → When you only read data

Entity Fetching → When you modify data

---

DTO Projection vs @EntityGraph

Feature	DTO Projection	@EntityGraph
What it returns	Returns a Data Transfer Object containing only selected fields	Returns a fully managed JPA entity
Primary use case	Best for read-only data such as API responses, dashboards, and reports	Best for business logic where entity behavior and updates are required
Fetch control	Controls exactly which columns are selected from the database	Controls which related entities are fetched eagerly
Updates allowed	Not allowed because DTOs are not managed by JPA	Allowed because entities are managed by the persistence context
Performance	Very high because only required fields are fetched	Good, but slower than DTOs because full entities are loaded
Memory usage	Low because partial data is stored	Higher because full entities and relationships are kept in memory
Lazy loading behavior	Not applicable because DTOs do not support lazy loading	Fully supported for non-selected associations
Risk of N+1 problem	Very low because data is fetched explicitly	Possible if associations are not included in the entity graph
Best for REST APIs	Highly recommended and safe	Not recommended for direct exposure
Complexity	Simple and lightweight	More complex due to entity management

---

Common Pitfalls

• Using DTO projections for update operations
• Incorrect constructor parameter order
• Expecting lazy loading in DTOs
• Overusing nested projections
• Putting business logic inside DTOs

---

Best Practices

• Use interface-based projections for simple queries
• Use constructor projections for complex logic
• Combine DTOs with pagination
• Prefer DTOs for REST APIs
• Keep DTOs immutable when possible
• Avoid exposing entities directly from controllers

---

Real-World Use Cases

• API response optimization
• Dashboard summaries
• Report generation
• Read-heavy microservices
• Large datasets with pagination

---

Visual Flow

Controller
   |
   |--> Repository
          |
          |--> DTO Projection
                 |
                 |--> Only required columns

---

Conclusion

• DTO Projections fetch only required fields
• Improve performance and reduce memory usage
• Prevent lazy loading and N+1 issues
• Support interface, class, and dynamic styles
• Ideal for clean, scalable, read-only APIs
• Complement @EntityGraph (not a replacement)