Spring Data JPA Projections: Interface, Record and Dynamic Projections (With the SQL They Generate)

Versions tested. Spring Boot 4.1.2 (4.1.0 went GA on June 10, 2026), Spring Data JPA 4.1.2, Hibernate ORM 7.4.13.Final, H2 2.4.240 in memory, JDK Temurin 25.0.5 LTS, JUnit via spring-boot-starter-data-jpa-test. Every SQL line and number below comes from a file in the companion repository’s output/ folder, regenerated by ./scripts/run-all.sh. H2 is not your production database: the shape of the SQL (which columns, how many statements) is what transfers; small dialect details such as fetch first ? rows only will differ.

A repository method returns whole rows, even when you need two columns

    // 1. Derived query, entity result (the baseline).
    List<Employee> findByDepartmentName(String departmentName);

# entity result: findByDepartmentName("Sales")
select e1_0.id,e1_0.bio,e1_0.department_id,e1_0.email,e1_0.first_name,e1_0.last_name,e1_0.salary from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
columns selected: 7, entities now managed by the persistence context: 4

public class SqlRecorder implements StatementInspector {
    private static final List<String> CAPTURED = new CopyOnWriteArrayList<>();

    @Override
    public String inspect(String sql) {
        CAPTURED.add(sql);
        return sql;
    }

    public static void clear() { CAPTURED.clear(); }

    public static List<String> captured() { return List.copyOf(CAPTURED); }

spring.jpa.properties.hibernate.session_factory.statement_inspector=com.ankurm.projections.SqlRecorder

A closed interface projection: declare only the getters you want

/** Closed interface projection: every getter matches an entity property, nothing computed. */
public interface EmployeeSummary {
    String getFirstName();
    String getLastName();
}

    // 2. Same derived query, closed interface projection.
    List<EmployeeSummary> findSummaryByDepartmentName(String departmentName);

# closed interface projection: findSummaryByDepartmentName("Sales")
select e1_0.first_name,e1_0.last_name from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
columns selected: 2, entities now managed by the persistence context: 0

# what an interface projection really is at runtime
is a java.lang.reflect.Proxy: true
is an Employee: false

Record DTOs: the same saving, as a real class

public record EmployeeDto(String firstName, String lastName) {}

    // 5. Record DTO projection.
    List<EmployeeDto> findDtoByDepartmentName(String departmentName);

# record DTO projection: findDtoByDepartmentName("Sales")
select e1_0.first_name,e1_0.last_name from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
columns selected: 2, entities now managed by the persistence context: 0

Dynamic projections: let the caller choose the shape

    // 6. Dynamic projection: the caller picks the shape.
    <T> List<T> findByDepartmentName(String departmentName, Class<T> type);

Employee         -> 4 rows, 7 columns: select e1_0.id,e1_0.bio,e1_0.department_id,e1_0.email,e1_0.first_name,e1_0.last_name,e1_0.salary
EmployeeSummary  -> 4 rows, 2 columns: select e1_0.first_name,e1_0.last_name
EmployeeDto      -> 4 rows, 2 columns: select e1_0.first_name,e1_0.last_name

org.springframework.data.core.PropertyReferenceException
No property 'nickname' found for type 'Employee'

The open projection trap: one @Value and you are back to full rows

public interface EmployeeFullName {
    @Value("#{target.firstName + ' ' + target.lastName}")
    String getFullName();
}

select e1_0.id,e1_0.bio,e1_0.department_id,e1_0.email,e1_0.first_name,e1_0.last_name,e1_0.salary from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
columns selected: 7, entities now managed by the persistence context: 4
getFullName() of first row: First1 Last1

The fingerprint of this bug. A repository method whose return type is a projection, yet the SQL in your logs lists every column of the table. Search your projection interfaces for @Value first.

/** Closed projection with a computed value: the computation is a plain default method, no SpEL. */
public interface EmployeeFullNameClosed {
    String getFirstName();
    String getLastName();

    default String getFullName() {
        return getFirstName() + " " + getLastName();
    }
}

select e1_0.first_name,e1_0.last_name from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
columns selected: 2, entities now managed by the persistence context: 0
getFullName() of first row: First1 Last1

Nested projections: convenient, but the join is not trimmed

/** Nested closed projection: one property reaches into the department association. */
public interface EmployeeWithDepartment {
    String getFirstName();
    DepartmentName getDepartment();

    interface DepartmentName {
        String getName();
    }
}

select e1_0.first_name,d1_0.id,d1_0.location,d1_0.name from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
columns selected: 4 (1 from employee + 3 from department), entities now managed: 1
department name read from the projection: Sales
extra statements after reading it: 0

@Query: aliases, constructor expressions and native queries

    // 7. @Query returning the entity but declared as an interface projection (aliases required).
    @Query("select e.firstName as firstName, e.lastName as lastName from Employee e where e.salary > :min")
    List<EmployeeSummary> richerThan(@Param("min") java.math.BigDecimal min);

    // 8. Constructor expression in JPQL.
    @Query("select new com.ankurm.projections.DepartmentPay(d.name, count(e), sum(e.salary)) "
         + "from Employee e join e.department d group by d.name order by d.name")
    List<DepartmentPay> payByDepartment();

    // 9. Native query + interface projection (alias must equal the getter name).
    @Query(value = "select first_name as firstName, last_name as lastName from employee where salary > :min", nativeQuery = true)
    List<EmployeeSummary> nativeRicherThan(@Param("min") java.math.BigDecimal min);

# @Query with aliases, declared as an interface projection
select e1_0.first_name,e1_0.last_name from employee e1_0 where e1_0.salary>?
rows: 6, first getFirstName(): First6

# @Query with a constructor expression (select new ...DepartmentPay)
select d1_0.name,count(e1_0.id),sum(e1_0.salary) from employee e1_0 join department d1_0 on d1_0.id=e1_0.department_id group by d1_0.name order by d1_0.name
DepartmentPay[department=Engineering, headcount=4, totalSalary=218000.00]
DepartmentPay[department=HR, headcount=4, totalSalary=226000.00]
DepartmentPay[department=Sales, headcount=4, totalSalary=222000.00]

# native query with column aliases equal to the getter names
select first_name as firstName, last_name as lastName from employee where salary > ?
rows: 6, first getFirstName(): First6

Three @Query traps that fail quietly

select e1_0.id,e1_0.bio,e1_0.department_id,e1_0.email,e1_0.first_name,e1_0.last_name,e1_0.salary from employee e1_0 where e1_0.salary>?
columns selected: 7, entities now managed: 6, rows: 6

select e1_0.first_name,e1_0.last_name from employee e1_0 where e1_0.salary>?
rows: 6
getFirstName() of first row: null
getLastName() of first row: null

The asymmetry to remember. For an interface projection, aliases are required. For a record DTO built with a constructor expression, the Spring Data docs say aliases must not be used. Same-looking queries, opposite rules.

select e1_0.first_name,e1_0.last_name from employee e1_0 where e1_0.salary>?
columns selected: 2, entities now managed: 0, rows: 6

Paging with a projection still runs a count query

# Page<EmployeeSummary>, page size 2
select e1_0.first_name,e1_0.last_name from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=? fetch first ? rows only
select count(*) from employee e1_0 left join department d1_0 on d1_0.id=e1_0.department_id where d1_0.name=?
statements: 2, rows in page: 2, total elements: 4

Which one should you use?

Should you do this everywhere? No. On a table with seven small columns and a few rows, the saving is invisible and projections add types to maintain. They pay off on wide tables, large text columns, hot read endpoints and list screens. Measure your own SQL log first; the figures here are column counts and managed-entity counts, not timings, because a real timing depends on your database and data. If you find yourself writing many hand-shaped read queries, it is also worth reading Spring Data JDBC vs Spring Data JPA.

Further reading

• Companion repository: spring-data-demo / projections — run ./scripts/run-all.sh to regenerate every transcript.
• Spring Data JPA reference: Projections.
• Spring Boot 4.1.0 announcement: spring.io.
• On this blog: Spring Boot CRUD REST API with Spring Data JPA, MapStruct with Spring Boot 4 and Java Records, Spring Data JDBC vs JPA.