Query Return Types

About

In JPA, query return types refer to the kind of data you expect back when executing a query (JPQL, Criteria, or Native SQL). Depending on the query and the method used, JPA can return:

• Single entities

• Scalar values (like Long, String, Integer)

• DTOs (custom projections)

• Aggregates

• Tuples (multiple fields)

• Collections

Characteristics

Return Type	Description
Entity	Returns full entity objects (mapped to a table).
DTO/Projection	Returns only selected fields using constructor expressions or interfaces.
Scalar	Returns basic types (e.g., count, sum, string).
List	Returns multiple results.
Single Result	Returns one result or throws exception if not found or more than one.
Tuple/Array	Returns multiple selected columns (e.g., in projections).

Syntax Structure

1. Entity Object (Default)

@Query("SELECT e FROM Employee e WHERE e.department = :dept")
List<Employee> findByDepartment(String dept);

2. Scalar Value

@Query("SELECT COUNT(e) FROM Employee e")
Long countEmployees();

3. Multiple Scalar Values (Array or Tuple)

@Query("SELECT e.name, e.salary FROM Employee e")
List<Object[]> findNameAndSalary();

for (Object[] row : resultList) {
   String name = (String) row[0];
   Double salary = (Double) row[1];
}

4. DTO via Constructor Expression (JPQL)

@Query("SELECT new com.example.EmployeeDTO(e.name, e.salary) FROM Employee e")
List<EmployeeDTO> findEmployeeDTOs();

DTO class

public class EmployeeDTO {
   public EmployeeDTO(String name, Double salary) {
       //...
   }
}

5. DTO via Interface (Spring Projections)

public interface EmployeeView {
    String getName();
    Double getSalary();
}

List<EmployeeView> findByDepartment(String department);

6. Single Result

@Query("SELECT e FROM Employee e WHERE e.id = :id")
Employee findOneById(Long id);