[QueryDSL] 결과 조회

QueryDSL로 쿼리를 작성할 때 마지막에 붙는 fetch(), fetchOne(), fetchFirst(), fetchResults(), fetchCount() 등의 메서드는 결과를 어떻게 가져올지를 결정한다.

이번 글에서는 각 메서드의 차이와 실제 동작 방식을 코드와 함께 정리해본다.

 

fetch() - 리스트 조회

List<Member> result = queryFactory
        .selectFrom(member)
        .fetch();

• 결과를 리스트로 반환한다.
• 조회 결과가 없으면 빈 리스트([])를 반환한다.
• JPQL의 getResultList()와 동일한 개념이다.
• 가장 일반적으로 사용되는 조회 메서드다.

 

fetchOne() - 단건 조회

Member findMember = queryFactory
        .selectFrom(member)
        .where(member.username.eq("member1"))
        .fetchOne();

• 결과가 한 건이면 해당 객체를 반환한다.
• 결과가 없으면 null을 반환한다.
• 결과가 둘 이상이면 NonUniqueResultException이 발생한다.

즉, 반드시 단 하나의 결과만 존재해야 할 때 사용해야 한다.
만약 여러 건 중 첫 번째 한 건만 조회하고 싶다면 fetchFirst()를 사용하는 것이 안전하다.

 

 

fetchFirst() - 첫 번째 한 건만 조회

Member firstMember = queryFactory
        .selectFrom(member)
        .fetchFirst();

• 내부적으로 limit(1)이 자동으로 붙는다.
• 결과가 여러 건이더라도 첫 번째 한 건만 반환한다.
• 실무에서는 테스트용이나 단일 조회에 자주 사용된다.

fetchFirst()는 사실상 limit(1).fetchOne()과 동일한 기능을 수행한다.

 

 

fetchResults() - 페이징 정보 포함 조회

QueryResults<Member> results = queryFactory
        .selectFrom(member)
        .offset(0)
        .limit(10)
        .fetchResults();

• 조회 쿼리와 count 쿼리가 두 번 실행된다.
• 반환 타입은 QueryResults<T>로, 내부에 페이징 정보와 전체 개수가 함께 담긴다.

results.getResults(); // 실제 데이터
results.getTotal();   // 전체 개수
results.getOffset();  // offset
results.getLimit();   // limit

단, QueryDSL 5.0 이상에서는 fetchResults()와 fetchCount()가 Deprecated 상태다.
최근 버전에서는 count 쿼리를 직접 작성하거나, Spring Data JPA의 Pageable 기능과 함께 사용하는 방식을 권장한다.

 

 

fetchCount() - count 쿼리만 실행

long count = queryFactory
        .selectFrom(member)
        .fetchCount();

• SELECT COUNT(*) 형태의 쿼리만 실행된다.
• 단순히 전체 데이터 개수만 조회할 때 사용한다.
• 역시 QueryDSL 5.0 이후로 Deprecated 되어 별도의 count 쿼리 작성이 권장된다.

 

마무리하며

QueryDSL에서는 상황에 따라 적절한 fetch 메서드를 선택해야 한다.

특히, fetchOne()과 fetchFirst()의 차이, 그리고 fetchResults()의 Deprecated 여부는 자주 혼동되는 부분이다.

페이징이 필요한 경우에는 Spring Data JPA의 Pageable 기능과 직접 count 쿼리를 조합해 사용하는 것이 가장 안정적이다

 

 

감사합니다.