Spring Data JPA 동적 쿼리: Query by Example(QBE) 심층 분석

애플리케이션 개발에서 데이터베이스 쿼리는 핵심적인 부분을 차지합니다. 특히 현대 웹 애플리케이션에서는 사용자의 다양한 입력에 따라 동적으로 변하는 검색 조건을 처리해야 하는 경우가 비일비재합니다. Spring Data JPA는 이러한 개발 과정을 크게 단순화시켜주는 강력한 도구이며, 개발자들은 JpaRepository가 제공하는 메소드 쿼리(예: findByFirstnameAndLastname)를 통해 손쉽게 데이터를 조회할 수 있습니다.

하지만 검색 조건이 몇 개만 추가되어도 메소드 이름은 걷잡을 수 없이 길어지고, 모든 조합을 미리 정의하는 것은 사실상 불가능에 가깝습니다. 이런 문제를 해결하기 위해 많은 개발자들이 JPQL(Java Persistence Query Language)과 @Query 어노테이션을 사용해 직접 쿼리 문자열을 작성하거나, 동적 쿼리 생성을 위해 문자열을 조합하는 방식을 택하곤 합니다. 이 방식은 유연하지만, 쿼리 문자열에 오타가 발생하기 쉽고 컴파일 시점에 오류를 잡을 수 없다는 단점이 있습니다. 또한, 조건 분기에 따라 if문이 덕지덕지 붙은 복잡한 서비스 로직을 야기하기도 합니다.

이러한 문제에 대한 대안으로 JPA Criteria API나 Querydsl과 같은 강력한 솔루션이 존재합니다. 이들은 타입-세이프(Type-safe)하게 동적 쿼리를 작성할 수 있게 해주지만, 별도의 학습 곡선이 필요하고 때로는 간단한 쿼리를 위해 상대적으로 복잡한 코드를 작성해야 한다는 부담이 있습니다. 그렇다면, 이 둘의 장점을 절충할 수 있는, 더 직관적이고 우아한 방법은 없을까요?

Spring Data JPA 1.10 버전부터 도입된 Query by Example (QBE)가 바로 그 해답이 될 수 있습니다. QBE는 '예제 객체'를 통해 쿼리를 정의하는 직관적인 방식을 제공하여, 보일러플레이트 코드 없이 타입-세이프하게 동적 쿼리를 작성할 수 있게 해줍니다. 이 글에서는 Query by Example의 기본 개념부터 고급 활용법, 그리고 그 한계와 적절한 사용 시점까지 심도 있게 파헤쳐 보겠습니다.

1. Query by Example (QBE) 핵심 개념 이해하기

QBE의 철학은 매우 간단합니다. "데이터를 담고 있는 실제 도메인 객체를 쿼리 조건의 예제로 사용하자." 입니다. 개발자는 찾고 싶은 데이터의 형태를 가진 '예제 객체(Probe)'를 생성하고, 이 객체를 Spring Data JPA에 전달하기만 하면 됩니다. 그러면 JPA는 이 예제 객체에 설정된 값들을 바탕으로 적절한 WHERE 절을 동적으로 생성해줍니다.

QBE를 구성하는 핵심 요소는 다음 세 가지입니다.

• Probe (프로브): 실제 쿼리 조건을 담고 있는 도메인 객체의 인스턴스입니다. 예를 들어, `firstname`이 "John"인 사용자를 찾고 싶다면 `Person` 객체를 생성하고 `setFirstname("John")`을 호출한 뒤 이 객체를 프로브로 사용합니다.
• ExampleMatcher (예제 매처): 프로브 객체의 필드를 어떻게 쿼리 조건으로 변환할지에 대한 규칙을 정의합니다. 문자열 검색 방식(정확히 일치, 시작 문자, 포함 등), 대소문자 구분 여부, 특정 필드 무시 등 세밀한 제어가 가능합니다. QBE 기능의 핵심이라고 할 수 있습니다.
• Example (예제): 프로브와 `ExampleMatcher`를 하나로 캡슐화한 객체입니다. 최종적으로 리포지토리에 전달되는 것이 바로 이 `Example` 객체입니다.

이러한 구성 요소를 사용하기 위해, 우리가 작성할 Repository 인터페이스는 `JpaRepository` 외에 QueryByExampleExecutor<T>를 추가로 상속해야 합니다. QueryByExampleExecutor 인터페이스는 QBE 쿼리를 실행할 수 있는 메소드들(예: `findOne`, `findAll`, `count`, `exists`)을 제공합니다.

// 예시: Person 엔티티
@Entity
public class Person {
    @Id
    @GeneratedValue
    private Long id;
    private String firstname;
    private String lastname;
    private Integer age;
    // Getters and Setters...
}

// 예시: PersonRepository 인터페이스
public interface PersonRepository extends JpaRepository, QueryByExampleExecutor {
    // JpaRepository의 기본 CRUD 메소드와
    // QueryByExampleExecutor의 QBE 관련 메소드를 모두 사용할 수 있다.
}

QBE의 가장 큰 장점은 다음과 같습니다.

• 직관성 및 가독성: 쿼리를 코드로 표현하는 것이 아니라, 실제 객체로 표현하므로 코드를 읽고 이해하기가 매우 쉽습니다.
• 보일러플레이트 감소: 동적 쿼리를 위한 복잡한 `if-else` 블록이나 문자열 조합 코드가 사라져 코드가 간결해집니다.
• 타입 안전성: 모든 것이 컴파일 시점에 타입 체크가 되므로, JPQL 문자열 오타와 같은 런타임 오류의 가능성을 원천적으로 차단합니다.
• 재사용성: 도메인 객체는 여러 비즈니스 로직에서 재사용될 수 있으며, 이를 그대로 쿼리 조건으로 활용할 수 있습니다.

2. QBE 시작하기: 기본 사용법과 동작 방식

백문이 불여일견입니다. 간단한 예제를 통해 QBE가 실제로 어떻게 동작하는지 살펴보겠습니다. 앞서 정의한 `Person` 엔티티와 `PersonRepository`를 사용한다고 가정합니다.

2.1. 가장 기본적인 QBE 쿼리

먼저 `firstname`이 "Bruce"이고 `lastname`이 "Wayne"인 사용자를 찾아보겠습니다.

@Autowired
private PersonRepository personRepository;

public void findBruceWayne() {
    // 1. 프로브(Probe) 객체 생성 및 조건 설정
    Person probe = new Person();
    probe.setFirstname("Bruce");
    probe.setLastname("Wayne");

    // 2. 프로브 객체로 Example 생성
    // ExampleMatcher를 명시하지 않으면 기본값이 사용된다.
    Example<Person> example = Example.of(probe);

    // 3. 쿼리 실행
    Optional<Person> result = personRepository.findOne(example);

    result.ifPresent(person -> System.out.println("Found: " + person.getFirstname()));
}

위 코드는 내부적으로 다음과 유사한 JPQL 쿼리를 생성하여 실행합니다.

-- 생성되는 JPQL 의사코드
SELECT p FROM Person p WHERE p.firstname = 'Bruce' AND p.lastname = 'Wayne';

여기서 주목해야 할 점은 기본 동작 방식입니다.

• Null 값 무시: 프로브 객체에서 `null`인 필드들(위 예제에서는 `id`, `age`)은 쿼리 조건에서 자동으로 제외됩니다. 이것이 동적 쿼리를 가능하게 하는 핵심적인 특징입니다. 만약 `probe.setLastname("Wayne")` 라인이 없었다면 `firstname`만으로 검색했을 것입니다.
• 문자열은 정확히 일치(Exact Match): 기본적으로 문자열 필드는 해당 값과 정확히 일치하는 데이터를 찾습니다.
• 대소문자 구분: 기본적으로 대소문자를 구분하여 검색합니다. 'bruce'는 'Bruce'와 다른 값으로 취급됩니다.
• 기본형(Primitive Type) 처리: 프로브 객체에 `int`, `boolean`과 같은 기본형 필드가 있고, 그 값이 기본값(예: `int`의 경우 0)이라면, 이 역시 쿼리 조건에 포함됩니다. `age`가 `Integer`가 아닌 `int`였다면 `probe`의 `age`는 0이므로 `WHERE ... AND p.age = 0` 조건이 추가되었을 것입니다. 이 때문에 일반적으로 엔티티에서는 래퍼 타입(Wrapper Type, 예: `Integer`, `Boolean`)을 사용하는 것이 권장됩니다.

3. ExampleMatcher: QBE 쿼리의 마에스트로

QBE의 진정한 힘은 `ExampleMatcher`를 통해 검색 규칙을 세밀하게 제어할 때 발휘됩니다. `ExampleMatcher`는 정적 팩토리 메소드(`matching()`, `matchingAll()`, `matchingAny()`)로 생성을 시작하며, 체이닝 방식을 통해 다양한 옵션을 설정할 수 있습니다.

이제 `ExampleMatcher`가 제공하는 주요 기능들을 상세한 예제와 함께 살펴보겠습니다.

3.1. 문자열 검색 전략 (String Matching Strategy)

가장 많이 사용되는 기능은 문자열 검색 방식을 지정하는 것입니다. `withStringMatcher()` 메소드를 사용하여 전체 문자열 필드에 대한 기본 검색 전략을 변경할 수 있습니다.

// 예시: lastname이 'ark'로 끝나고, firstname이 'St'로 시작하는 모든 사람 찾기
Person probe = new Person();
probe.setFirstname("St"); // Tony Stark, Steve Rogers 등
probe.setLastname("ark"); // Tony Stark, ...

ExampleMatcher matcher = ExampleMatcher.matching()
    // firstname 필드는 '시작 문자' 기준으로 검색 (startsWith)
    .withMatcher("firstname", ExampleMatcher.GenericPropertyMatchers.startsWith())
    // lastname 필드는 '끝나는 문자' 기준으로 검색 (endsWith)
    .withMatcher("lastname", ExampleMatcher.GenericPropertyMatchers.endsWith());

Example<Person> example = Example.of(probe, matcher);
List<Person> results = personRepository.findAll(example);

위 코드에서 `withMatcher(String propertyPath, MatcherConfigurer<GenericPropertyMatcher>)` 메소드는 특정 필드(`"firstname"`, `"lastname"`)에 대해 개별적인 검색 규칙을 적용합니다. `ExampleMatcher.GenericPropertyMatchers`는 미리 정의된 유용한 매처들을 제공합니다.

• `exact()`: 정확히 일치 (기본값)
• `startsWith()`: 시작 문자 일치 (SQL의 `LIKE 'text%'`)
• `endsWith()`: 끝나는 문자 일치 (SQL의 `LIKE '%text'`)
• `contains()`: 포함 문자 일치 (SQL의 `LIKE '%text%'`)
• `ignoreCase()`: 대소문자를 무시하고 매칭합니다. 이 자체로 매칭 전략이라기보다는 다른 전략과 조합됩니다. (예: `startsWith().ignoreCase()`)
• `caseSensitive()`: 대소문자를 구분합니다 (기본값).

만약 모든 문자열 필드에 동일한 전략을 적용하고 싶다면 `withStringMatcher()`를 사용하면 편리합니다.

// 모든 문자열 속성에 대해 '포함' 검색 적용
ExampleMatcher matcher = ExampleMatcher.matching()
    .withStringMatcher(ExampleMatcher.StringMatcher.CONTAINING);

// Example 생성 및 쿼리는 동일

3.2. 대소문자 무시 (Case Insensitivity)

대소문자 구분은 매우 흔한 요구사항입니다. `ignoreCase()`를 사용하면 간단하게 처리할 수 있습니다.

// 예시: firstname이 대소문자 구분없이 'bruce'인 사람 찾기
Person probe = new Person();
probe.setFirstname("bruce");

// 1. 특정 필드에만 대소문자 무시 적용
ExampleMatcher specificMatcher = ExampleMatcher.matching()
    .withMatcher("firstname", ExampleMatcher.GenericPropertyMatchers.exact().ignoreCase());

Example<Person> specificExample = Example.of(probe, specificMatcher);
List<Person> result1 = personRepository.findAll(specificExample); // "Bruce", "bruce", "BRUCE" 모두 찾음

// 2. 모든 필드에 대소문자 무시 일괄 적용
ExampleMatcher globalMatcher = ExampleMatcher.matching()
    .withIgnoreCase();

Example<Person> globalExample = Example.of(probe, globalMatcher);
List<Person> result2 = personRepository.findAll(globalExample); // 결과 동일

withIgnoreCase(String... propertyPaths)를 사용하여 특정 필드들에만 대소문자 무시를 적용할 수도 있습니다.

3.3. 특정 속성 제외하기 (`ignorePaths`)

때로는 프로브 객체에 값이 설정되어 있더라도 쿼리 조건에서는 제외하고 싶을 때가 있습니다. 예를 들어, UI에서 받은 DTO를 엔티티로 변환하여 프로브로 사용할 때, 검색 조건이 아닌 필드(예: `id`, `modifiedDate`)가 포함될 수 있습니다. 이때 `withIgnorePaths()`를 사용합니다.

// 예시: firstname으로만 검색하고, age는 30이지만 쿼리 조건에서 제외하기
Person probe = new Person();
probe.setFirstname("Clark");
probe.setAge(30); // 이 값은 무시하고 싶음

ExampleMatcher matcher = ExampleMatcher.matching()
    .withIgnorePaths("age", "id"); // age와 id 필드는 쿼리 조건에서 제외

Example<Person> example = Example.of(probe, matcher);
List<Person> results = personRepository.findAll(example);
// 생성되는 쿼리는 "SELECT p FROM Person p WHERE p.firstname = 'Clark'" 가 된다.
// age 조건은 포함되지 않는다.

3.4. Null 값 처리 (`withIncludeNullValues` vs `withIgnoreNullValues`)

앞서 언급했듯이 QBE의 기본 동작은 `null` 값을 무시하는 것입니다(`withIgnoreNullValues()`). 하지만 드물게는 특정 필드의 값이 `NULL`인 데이터를 명시적으로 찾고 싶을 수도 있습니다. 이 경우 `withIncludeNullValues()`를 사용할 수 있습니다.

// 예시: lastname은 'Kent'이고 age가 NULL인 사람 찾기
Person probe = new Person();
probe.setLastname("Kent");
probe.setAge(null); // age가 null인 것을 조건으로 사용하고 싶음

// ExampleMatcher를 통해 null 포함을 활성화
ExampleMatcher matcher = ExampleMatcher.matching()
    .withIncludeNullValues(); // age 필드가 null인 조건을 쿼리에 포함시킴

Example<Person> example = Example.of(probe, matcher);
List<Person> results = personRepository.findAll(example);
// 생성되는 쿼리: "SELECT p FROM Person p WHERE p.lastname = 'Kent' AND p.age IS NULL"

주의: `withIncludeNullValues()`는 모든 `null` 필드를 `IS NULL` 조건으로 변환합니다. 만약 프로브에서 `firstname`도 `null`이었다면, `WHERE p.lastname = 'Kent' AND p.age IS NULL AND p.firstname IS NULL` 과 같은 쿼리가 생성됩니다. 특정 필드만 `IS NULL` 검색을 하고 싶다면 다른 필드에는 값을 채워넣거나, 이 경우에는 QBE보다 JPA Specifications를 사용하는 것이 더 적합할 수 있습니다.

3.5. 모든 조건 매칭(AND) vs 하나라도 매칭(OR)

지금까지의 모든 예제는 프로브에 설정된 조건들을 `AND`로 연결했습니다. `ExampleMatcher.matching()` 또는 `ExampleMatcher.matchingAll()`이 기본 `AND` 조건을 사용하기 때문입니다. 만약 조건들을 `OR`로 연결하고 싶다면 `matchingAny()`를 사용하면 됩니다.

// 예시: firstname이 'Peter' 이거나 lastname이 'Parker'인 사람 찾기
Person probe = new Person();
probe.setFirstname("Peter");
probe.setLastname("Parker");

ExampleMatcher matcher = ExampleMatcher.matchingAny(); // OR 조건으로 변경

Example<Person> example = Example.of(probe, matcher);
List<Person> results = personRepository.findAll(example);

// 생성되는 쿼리: "SELECT p FROM Person p WHERE p.firstname = 'Peter' OR p.lastname = 'Parker'"

이는 매우 강력한 기능이지만, 한 가지 중요한 제약사항이 있습니다. `matchingAny`는 프로브에 명시된 모든 non-null 속성들을 `OR`로 묶습니다. `firstname = 'Peter' OR age > 30`과 같이 서로 다른 필드를 `OR`로 묶되, `lastname`은 `AND`로 묶는 식의 복잡한 `AND`/`OR` 조합은 QBE만으로 표현할 수 없습니다.

3.6. 값 변환 (`withTransformer`)

때로는 쿼리에 사용되기 전에 프로브의 속성 값을 변환해야 할 필요가 있습니다. 예를 들어, 문자열 검색 시 항상 소문자로 변경하여 비교하고 싶을 때 `withTransformer`를 사용할 수 있습니다. `PropertyValueTransformer` 람다식을 인자로 받습니다.

// 예시: firstname 검색 시 프로브 값을 소문자로 변환하여 비교
Person probe = new Person();
probe.setFirstname("TONY");

ExampleMatcher matcher = ExampleMatcher.matching()
    .withMatcher("firstname", ExampleMatcher.GenericPropertyMatchers.contains())
    // firstname 필드에 값 변환기(transformer) 적용
    .withTransformer("firstname", value -> Optional.of(value.toString().toLowerCase()));

Example<Person> example = Example.of(probe, matcher);
List<Person> results = personRepository.findAll(example);
// 내부적으로 probe의 'TONY'를 'tony'로 변환한 후, 'tony'를 포함하는 데이터를 검색
// (DB 컬럼도 lower() 함수를 적용해야 올바른 비교가 되므로, 
//  보통은 ignoreCase()를 사용하는 것이 더 일반적이고 효율적입니다)

이 기능은 특정 형식의 날짜 문자열을 `LocalDate` 객체로 변환하는 등 보다 복잡한 시나리오에서 유용하게 사용될 수 있습니다.

4. QBE의 한계와 적절한 사용 시점

Query by Example은 매우 편리하고 직관적인 도구이지만, 만병통치약은 아닙니다. QBE의 명확한 한계를 이해하고, 언제 사용하는 것이 가장 효과적인지 아는 것이 중요합니다.

4.1. QBE의 명백한 한계점

• 범위(Range) 쿼리 미지원: 숫자나 날짜에 대한 범위 검색(예: `age > 30`, `createdAt BETWEEN '2023-01-01' AND '2023-12-31'`)을 직접적으로 지원하지 않습니다. 프로브에 설정된 값은 '같다'(`=`) 또는 `LIKE` 조건을 위해서만 사용됩니다.
• 복잡한 조건 조합의 어려움: 앞서 언급했듯이, `(A AND B) OR C` 와 같이 여러 필드를 섞어 복잡한 `AND`/`OR` 논리 조합을 만드는 것은 불가능합니다. QBE는 전체 조건을 `AND`로 묶거나(`matchingAll`) `OR`로 묶는(`matchingAny`) 두 가지 방식만 제공합니다.
• 중첩/연관 속성(Nested/Associated Properties) 제한: QBE는 연관 관계에 있는 엔티티의 속성을 조건으로 사용하는 데 제한이 있습니다. 예를 들어, `Person`이 `Address` 엔티티를 가지고 있을 때, `person.address.city = 'Gotham'`과 같은 조건은 직접적으로 지원되지 않습니다. 연관 객체 자체를 프로브에 설정하여 외래 키를 기준으로 한 동등 비교(`person.address = :address_id`)는 가능하지만, 그 이상의 세부적인 필드 탐색은 어렵습니다.
• 프로퍼티 레벨이 아닌 그룹화 및 집계 함수 미지원: `GROUP BY`, `HAVING` 이나 `COUNT`, `SUM`, `AVG` 같은 집계 함수를 사용하는 쿼리는 QBE의 설계 범위를 벗어납니다.

4.2. 언제 QBE를 선택해야 할까?

이러한 한계에도 불구하고 QBE가 빛을 발하는 시나리오는 분명히 존재합니다.

QBE를 사용하기 좋은 경우 (Use QBE)	다른 대안을 고려해야 하는 경우 (Consider Alternatives)
간단한 동적 검색 화면: 관리자 페이지 등에서 여러 선택적 필드를 가진 검색 폼을 구현할 때. 프로토타이핑: 빠르게 데이터 조회 기능을 구현하고 싶을 때. 데이터 존재 여부 확인: 특정 속성 조합을 가진 데이터가 있는지 간단히 확인할 때 (`exists(example)`). 쿼리 조건이 대부분 `AND`로 연결될 때. 도메인 객체와 쿼리 조건의 구조가 거의 동일할 때.	복잡한 통계 및 리포팅 쿼리: `GROUP BY`, 집계 함수가 필요한 경우. 범위 검색이 필수적인 경우: 가격, 나이, 날짜 등 범위로 데이터를 필터링해야 할 때. 복잡한 `OR` 조건이 필요할 때: `(firstname = 'A' AND age > 20) OR (lastname = 'B')`와 같은 쿼리. 연관 엔티티의 속성을 깊게 탐색해야 할 때(조인 후 조건).

복잡한 요구사항이 발생했을 때의 대안은 명확합니다. JPA Criteria API나 Querydsl을 사용하면 QBE가 가진 거의 모든 한계를 극복하고, 타입-세이프하면서도 매우 정교하고 복잡한 동적 쿼리를 작성할 수 있습니다.

5. 결론: 동적 쿼리를 위한 현명한 도구 선택

Spring Data JPA의 Query by Example(QBE)는 동적 쿼리를 처리하는 매우 직관적이고 우아한 방법을 제공합니다. 특히 간단하거나 중간 정도 복잡성의 '예제로 질의하기' 시나리오에서, 복잡한 문자열 조합이나 Criteria API의 장황함 없이도 가독성 높고 유지보수하기 쉬운 코드를 작성하게 해줍니다. 개발자는 `Example`과 `ExampleMatcher`를 통해 보일러플레이트를 대폭 줄이고 비즈니스 로직에 더 집중할 수 있습니다.

그러나 QBE는 모든 문제를 해결하는 은 탄환이 아닙니다. 범위 검색, 복잡한 논리 조합, 깊은 연관 관계 탐색과 같은 고급 쿼리 요구사항에는 명확한 한계를 가집니다. 성공적인 기술 선택은 각 도구의 장점과 한계를 정확히 이해하는 것에서 시작됩니다.

여러분의 프로젝트에서 마주한 동적 쿼리 요구사항을 분석해보십시오. 만약 그 요구사항이 QBE의 장점이 극대화되는 영역에 있다면, 주저 없이 도입하여 코드의 품질을 한 단계 끌어올릴 수 있을 것입니다. 만약 그 범위를 넘어선다면, Querydsl이나 JPA Specifications와 같은 더 강력한 도구를 준비하는 것이 현명한 전략일 것입니다. 결국, QBE는 Spring Data JPA 개발자의 도구 상자에 반드시 갖춰두어야 할 유용한 연장 중 하나임이 틀림없습니다.