본문으로 건너뛰기
목록으로

Spring Data JPA, QueryDSL JPA, QueryDSL SQL은 어떻게 다른가 — JPQL은 어디에 속하나

Johny Cho
Software Engineer @ Kurly

JPA 프로젝트에서 조회 코드를 작성하다 보면 Spring Data JPA, QueryDSL, JPQL, 네이티브 쿼리가 한 저장소 안에 섞여 있습니다. 여기에 QueryDSL이 JPA 모듈과 SQL 모듈 두 가지라는 사실까지 더해지면 "무엇이 무엇 위에서 동작하는지"가 헷갈리기 쉽습니다. 이 글은 세 기술의 위치를 레이어 기준으로 정리하고, 어떤 상황에 무엇을 고르는지 살펴봅니다.

판단 기준은 "그 쿼리가 EntityManager(영속성 컨텍스트)를 거치는가" 한 가지입니다 — Spring Data JPA와 QueryDSL JPA는 거치고, QueryDSL SQL은 거치지 않습니다.

JPQL은 어디에 속하나 — JPA 명세​

JPQL(Java Persistence Query Language)은 JPA 표준 명세에 정의된 쿼리 언어입니다. Jakarta Persistence 명세 4장 "Query Language"가 문법과 의미를 규정하고, Hibernate, EclipseLink 같은 구현체가 이를 해석해 SQL로 변환합니다.

  • JPQL — JPA 명세 소속. 테이블과 컬럼이 아니라 엔티티와 필드를 대상으로 작성합니다.
  • HQL — Hibernate 소속. JPQL을 포함하는 상위 집합입니다.
  • Spring Data JPA, QueryDSL — 어느 쪽도 JPQL을 "소유"하지 않습니다. JPQL을 만들어서 EntityManager에 넘기는 쪽입니다.
// JPQL — 엔티티 Order와 필드 status를 대상으로 작성
String jpql = "select o from Order o where o.status = :status";
List<Order> orders = em.createQuery(jpql, Order.class)
.setParameter("status", OrderStatus.PAID)
.getResultList();

JPA와 Hibernate의 관계(명세와 구현체)는 JPA와 Hibernate는 무슨 관계인가에서 자세히 설명했습니다.

세 기술의 위치​

PlantUML 코드
@startuml
skinparam shadowing false
skinparam defaultFontName sans-serif
rectangle "Spring Data JPA\nRepository, 쿼리 메서드" as SD #EEF3FB
rectangle "QueryDSL JPA\nJPAQueryFactory" as QJ #EEF3FB
rectangle "JPA (표준 명세)\nEntityManager, JPQL" as J #E9F2E9
rectangle "Hibernate\n영속성 컨텍스트" as H #FCE4EC
rectangle "QueryDSL SQL\nSQLQueryFactory" as QS #FFF8E1
rectangle "JDBC" as D #FFF3E0
database "DB" as DB
SD --> J : JPQL, Criteria
QJ --> J : JPQL 문자열
J --> H
H --> D : SQL
QS --> D : SQL 직접
D --> DB
@enduml

PlantUML Spring Data JPA, QueryDSL JPA, QueryDSL SQL의 레이어 위치

그림에서 왼쪽 두 기술(Spring Data JPA, QueryDSL JPA)은 모두 JPA로 내려가 같은 영속성 컨텍스트를 사용합니다. 오른쪽 QueryDSL SQL은 JPA, Hibernate를 지나지 않고 JDBC를 바로 호출합니다. 그래서 Spring Data JPA와 QueryDSL JPA는 한 트랜잭션에서 함께 사용해도 엔티티를 공유하지만, QueryDSL SQL의 결과는 영속성 컨텍스트와 무관한 값입니다.

Spring Data JPA vs QueryDSL JPA — 대체가 아니라 조합​

두 기술은 맡는 일이 다릅니다.

구분Spring Data JPAQueryDSL JPA
하는 일리포지토리 구현을 자동 생성타입 안전한 JPQL을 코드로 작성
쿼리 작성 방식메서드 이름 파생, @Query(JPQL 문자열)Q 타입 + 메서드 체인
오타 발견 시점@Query 문자열은 애플리케이션 기동 시컴파일 시
동적 조건Specification 등으로 가능하지만 장황함BooleanBuilder, where(null 무시)로 간결
실행 경로EntityManagerEntityManager

Spring Data JPA의 SimpleJpaRepository는 내부에서 EntityManager를 그대로 호출합니다. 예를 들어 findById는 em.find입니다.

// spring-data-jpa: SimpleJpaRepository#findById (발췌)
public Optional<T> findById(ID id) {
...
if (metadata == null) {
return Optional.ofNullable(entityManager.find(domainType, id));
}
...
}

→ Spring Data JPA는 JPA 위의 편의 계층이고, 실제 조회는 JPA가 수행합니다. (SimpleJpaRepository.java)

QueryDSL JPA도 마찬가지입니다. 메서드 체인으로 만든 쿼리를 JPQL 문자열로 직렬화한 뒤 EntityManager.createQuery로 실행합니다.

// querydsl-jpa: AbstractJPAQuery#createQuery (발췌)
protected Query createQuery(@Nullable QueryModifiers modifiers, boolean forCount) {
JPQLSerializer serializer = serialize(forCount);
String queryString = serializer.toString();
...
Query query = entityManager.createQuery(queryString);

→ QueryDSL JPA는 "JPQL 빌더"입니다. JPQL로 표현할 수 없는 SQL(예: FROM 절 서브쿼리를 사용하는 구문)은 QueryDSL JPA로도 작성할 수 없습니다. (AbstractJPAQuery.java)

실무에서는 두 기술을 한 리포지토리에 함께 구성합니다. 단순 CRUD, 단건 조회는 Spring Data JPA에 맡기고, 조건이 많은 검색 쿼리만 커스텀 구현체에서 QueryDSL로 작성합니다.

public interface OrderRepository
extends JpaRepository<Order, Long>, OrderRepositoryCustom { }

public interface OrderRepositoryCustom {
List<Order> search(OrderSearchCondition cond);
}

// 클래스 이름은 "인터페이스 이름 + Impl" 규칙을 따른다
class OrderRepositoryCustomImpl implements OrderRepositoryCustom {
private final JPAQueryFactory queryFactory;

OrderRepositoryCustomImpl(EntityManager em) {
this.queryFactory = new JPAQueryFactory(em);
}

@Override
public List<Order> search(OrderSearchCondition cond) {
return queryFactory.selectFrom(order)
.where(statusEq(cond.status()),
createdAfter(cond.from()))
.fetch();
}

// null을 반환하면 where 조건에서 제외된다
private BooleanExpression statusEq(OrderStatus status) {
return status == null ? null : order.status.eq(status);
}

private BooleanExpression createdAfter(LocalDateTime from) {
return from == null ? null : order.createdAt.after(from);
}
}
OrderRepository만으로 save, findById(Spring Data JPA)와 search(QueryDSL JPA)를 함께 호출할 수 있고, 두 경로 모두 같은 EntityManager를 사용합니다.

QueryDSL JPA vs QueryDSL SQL​

이름은 같은 QueryDSL이지만 대상 언어와 실행 경로가 다른 모듈입니다.

구분QueryDSL JPA (querydsl-jpa)QueryDSL SQL (querydsl-sql)
생성하는 쿼리JPQLSQL (DB 방언별)
Q 타입 생성 원천@Entity 클래스 (애너테이션 프로세서)DB 스키마 메타데이터 (코드 생성기가 테이블을 읽음)
실행 경로EntityManagerJDBC Connection
결과엔티티(영속 상태) 또는 DTO값, DTO (엔티티 개념 없음)
변경 감지, 지연 로딩사용 가능없음
SQL 표현 범위JPQL 범위 내union, FROM 절 서브쿼리, 윈도우 함수 등 SQL 기능 대부분

QueryDSL SQL은 이렇게 사용합니다. Q 타입이 엔티티가 아니라 테이블을 나타냅니다.

SQLQueryFactory sqlQueryFactory = new SQLQueryFactory(
new Configuration(MySQLTemplates.builder().build()),
dataSource);

QOrders o = QOrders.orders; // DB 테이블 orders에서 생성된 Q 타입
ConstructorExpression<OrderSummary> summary =
Projections.constructor(OrderSummary.class, o.memberId, o.amount.sum());
List<OrderSummary> rows = sqlQueryFactory.select(summary)
.from(o)
.groupBy(o.memberId)
.fetch();

QueryDSL SQL이 유용한 경우는 다음과 같습니다.

  • 통계, 리포트 쿼리 — 윈도우 함수, union, 복잡한 서브쿼리처럼 JPQL로 표현하기 어려운 SQL을 타입 안전하게 작성할 때.
  • 엔티티가 없는 테이블 — 레거시 테이블이나 집계 테이블을 엔티티로 매핑하지 않고 조회만 할 때.
  • 대량 처리 — 영속성 컨텍스트에 엔티티를 쌓지 않고 값만 읽어 메모리 사용을 줄일 때.

JPA 프로젝트에 QueryDSL SQL을 함께 사용하면 무엇을 주의하나?

QueryDSL SQL은 영속성 컨텍스트를 모르기 때문에 두 가지를 확인해야 합니다. ① 같은 트랜잭션의 커넥션을 사용하는지 — querydsl-sql-spring의 SpringConnectionProvider로 Spring 트랜잭션에 참여시켜야 JPA와 같은 트랜잭션에서 실행됩니다. ② flush 전 변경은 보이지 않습니다 — JPA로 수정한 엔티티가 아직 flush되지 않았다면 QueryDSL SQL은 변경 전 값을 읽습니다. JPA의 JPQL, 네이티브 쿼리는 실행 전에 자동 flush가 발생하지만, JPA를 거치지 않는 QueryDSL SQL, JdbcTemplate에는 이 동작이 없으므로 필요하면 em.flush()를 먼저 호출합니다.

flush가 언제 발생하는지는 JPA와 Hibernate에서 flush, commit, rollback은 언제 실행되나에 정리돼 있습니다.

무엇을 고르나​

상황별로 차례로 대입해 보면 다음과 같습니다.

  1. 엔티티를 저장하거나 수정하고, 단건이나 단순 조건으로 조회한다 → Spring Data JPA. 쿼리 메서드와 save만으로 충분합니다.
  2. 검색 조건이 동적으로 바뀌고 결과가 엔티티다 → QueryDSL JPA. Spring Data JPA의 @Query는 문자열이라 조건 조합이 어렵고, 결과를 엔티티로 받아 변경 감지까지 사용하려면 JPA 경로여야 합니다.
  3. 통계, 집계처럼 JPQL로 표현하기 어려운 SQL이고 결과가 값이다 → QueryDSL SQL(또는 네이티브 쿼리). 영속성 컨텍스트가 필요 없고, JPQL 문법 제약을 받지 않습니다.
기술실행 경로결과가 영속 엔티티인가주 용도
Spring Data JPAEntityManager예 (엔티티 조회 시)CRUD, 단순 조회
QueryDSL JPAEntityManager예 (엔티티 조회 시)동적 검색
QueryDSL SQLJDBC아니오통계, 복잡한 SQL

QueryDSL 프로젝트 현황

원 프로젝트(com.querydsl)는 5.x 이후 릴리스가 뜸해졌고, OpenFeign이 포크해 유지보수를 이어가는 io.github.openfeign.querydsl도 있습니다. 새로 도입한다면 사용하는 Spring Boot, Hibernate 버전과의 호환성을 두 프로젝트 기준으로 확인합니다.

정리​

  • JPQL은 JPA 명세에 속한 쿼리 언어이고, Hibernate는 이를 해석하는 구현체입니다. Spring Data JPA, QueryDSL JPA는 JPQL을 만들어 EntityManager에 넘기는 도구입니다.
  • Spring Data JPA와 QueryDSL JPA는 함께 사용합니다 — CRUD는 Spring Data JPA, 동적 검색은 QueryDSL JPA로 나누고, 둘 다 같은 영속성 컨텍스트를 사용합니다.
  • QueryDSL SQL은 JPA를 거치지 않습니다 — 결과는 영속 엔티티가 아니고, 자동 flush도 발생하지 않습니다. JPQL로 어려운 SQL이 필요할 때 선택합니다.

참고​