[ 트러블 슈팅 ] Elasticsearch keyword 필드의 중요성 (term 쿼리가 안될 때)

Elasticsearch에서 term 쿼리가 동작하지 않는 문제 해결

 

문제 상황

채용 공고 데이터를 조회하는 기능을 Spring API와 Elasticsearch를 연동하여 구현하던 중, 자격 요건(requiredSkills)을 term 쿼리를 통해 필터링했더니 데이터가 전혀 조회되지 않는 현상이 발생했다.

---

기존 쿼리

// 자격 요건 필터링
if (requestDto.getRequiredSkill() != null) {
    boolQueryBuilder.filter(f -> f
        .term(t -> t
            .field("requiredSkills")
            .value(requestDto.getRequiredSkill())
        )
    );
}

---

원인 분석

먼저 Elasticsearch에서 저장된 데이터를 확인해 봤다.

GET job-opening/_mapping

확인 결과 requiredSkills 필드의 매핑이 다음과 같이 설정되어 있었다.

"requiredSkills": {
  "type": "text",
  "fields": {
    "keyword": {
      "type": "keyword",
      "ignore_above": 256
    }
  }
}

여기서 중요한 것은 term 쿼리는 정확히 일치하는 키워드를 검색하는 방식이기 때문에 analyzer가 적용되는 text 타입 필드에서 제대로 동작하지 않는 것이다.

• text 타입: analyzer를 통해 단어가 분리되어 저장됨 (정확한 일치 검색 불가)
• keyword 타입: analyzer 없이 정확한 키워드 형태로 저장됨 (정확한 일치 검색 가능)

---

해결 방법

정확한 키워드 매칭을 위해서는 반드시 .keyword 필드를 사용해야 한다.

수정한 쿼리

// 자격 요건 필터링
if (requestDto.getRequiredSkill() != null) {
    boolQueryBuilder.filter(f -> f
        .term(t -> t
            .field("requiredSkills.keyword")
            .value(requestDto.getRequiredSkill())
        )
    );
}

---

결과 확인

쿼리를 수정한 후 다시 테스트했더니 정상적으로 데이터가 조회되는 것을 확인할 수 있었다.

주의할 점

• Elasticsearch에서 정확히 일치하는 키워드로 데이터를 조회할 땐 항상 keyword 타입을 사용하자.
• term 쿼리는 analyzer가 적용되지 않은 필드(keyword)에서만 정확한 결과를 얻을 수 있다.