전체 아티클 목록으로
Database • 2026-11-11 • 약 5분 분량

Elasticsearch - Analyzer

Elasticsearch 전문 검색의 심장인 Analyzer(분석기)의 내부 동작 메커니즘, _analyze API를 통한 토큰 검증, 5대 기본 내장 분석기 및 사용자 정의 Custom Analyzer 완벽 정리.

#Elasticsearch #Analyzer #Tokenizer #Token Filter #Custom Analyzer
[광고 영역] AdSense Top Unit Slot

Elasticsearch - Analyzer

본 포스팅의 모든 실습과 예제는 Elasticsearch 7.6 버전을 기준으로 작성되었다.

지난 5편에서 스키마에 해당하는 매핑(Mapping)과 데이터 타입을 다루었으니, 이번에는 text 타입의 문자열이 어떻게 검색 가능한 텀(Term)으로 쪼개지고 가공되는지 결정하는 분석기(Analyzer)의 내부 구조와 활용법에 대해 알아본다.


1. 분석기(Analyzer)의 개념과 3단계 파이프라인

Elasticsearch에서 도큐먼트를 색인(Indexing)할 때, 텍스트 데이터를 검색에 유리한 형태인 텀(Term)으로 추출하기 위해 거치는 일련의 처리 과정을 분석(Analysis)이라고 하며, 이를 수행하는 모듈을 분석기(Analyzer)라고 부른다.

분석기는 내부적으로 다음과 같은 순서로 데이터를 처리한다:

[원본 텍스트]
      │
      ▼
1. 캐릭터 필터 (Character Filter, 0개 이상) ──▶ HTML 태그 제거, 특정 기호 치환
      │
      ▼
2. 토크나이저 (Tokenizer, 반드시 1개)       ──▶ 공백, 구두점 기준으로 단어(Token) 분리
      │
      ▼
3. 토큰 필터 (Token Filter, 0개 이상)        ──▶ 소문자화, 불용어 제거, 동의어 처리
      │
      ▼
[최종 검색용 텀(Terms) 추출 및 역인덱스 저장]

분석 과정의 단계별 예시

다음과 같은 문자열이 입력되었을 때:

"The 2 QUICK Brown-Foxes jumped over the lazy dog bone."

  1. whitespace 토크나이저 통과 후 (공백 기준 분리): text ["The", "2", "QUICK", "Brown-Foxes", "jumped", "over", "the", "lazy", "dog", "bone."]
  2. lowercase 토큰 필터 통과 후 (모두 소문자로 변환): text ["the", "2", "quick", "brown-foxes", "jumped", "over", "the", "lazy", "dog", "bone."]
  3. stop 토큰 필터 통과 후 (의미 없는 불용어 the 제거): text ["2", "quick", "brown-foxes", "jumped", "over", "lazy", "dog", "bone."]

2. _analyze API를 활용한 실시간 분석기 테스트

Elasticsearch는 작성한 텍스트가 실제로 어떤 토큰으로 분리되는지 사전에 검증할 수 있는 _analyze REST API를 제공한다.

2.1 토크나이저만 단독 적용

curl -H 'Content-Type: application/json' -X GET 'localhost:9200/_analyze?pretty' -d '
{
  "tokenizer": "whitespace",
  "filter": [],
  "text": "The 2 QUICK Brown-Foxes jumped over the lazy dog bone."
}'
/* 반환 결과 (토큰 단위 분리 확인) */
{
  "tokens": [
    { "token": "The", "start_offset": 0, "end_offset": 3, "type": "word", "position": 0 },
    { "token": "2", "start_offset": 4, "end_offset": 5, "type": "word", "position": 1 },
    { "token": "QUICK", "start_offset": 6, "end_offset": 11, "type": "word", "position": 2 },
    { "token": "Brown-Foxes", "start_offset": 12, "end_offset": 23, "type": "word", "position": 3 },
    ...
  ]
}

2.2 토큰 필터 체이닝 (소문자화 + 불용어 제거)

curl -H 'Content-Type: application/json' -X GET 'localhost:9200/_analyze?pretty' -d '
{
  "tokenizer": "whitespace",
  "filter": ["lowercase", "stop"],
  "text": "The 2 QUICK Brown-Foxes jumped over the lazy dog bone."
}'
/* 반환 결과 (대문자가 소문자로 바뀌고, 불용어 the가 제거됨) */
{
  "tokens": [
    { "token": "2", ... },
    { "token": "quick", ... },
    { "token": "brown-foxes", ... },
    { "token": "jumped", ... },
    { "token": "over", ... },
    { "token": "lazy", ... },
    { "token": "dog", ... },
    { "token": "bone.", ... }
  ]
}

⚠️ 토큰 필터 순서의 중요성:
둘 이상의 토큰 필터를 적용할 때는 배열에 명시된 순서대로 순차 실행된다. 예를 들어 lowercase 필터가 stop 필터보다 뒤에 오면, 대문자로 시작하는 불용어 "The"가 제거되지 않고 남을 수 있으므로 항상 순서 설계에 유의해야 한다.


3. 엘라스틱서치 5대 기본 내장 분석기 (Built-in Analyzers)

Elasticsearch는 사전 설정 없이 즉시 사용할 수 있는 다양한 기본 내장 분석기를 제공한다.

분석기 명칭 구성 (Tokenizer / Filters) 특징 및 동작 방식
standard Standard Tokenizer
+ Lowercase, Stop Filter
기본 분석기. 유니코드 텍스트 기반 분리, 소문자화, 기본 불용어 처리
simple Lowercase Tokenizer 영문자가 아닌 모든 문자(숫자, 공백, 기호)를 기준으로 단어를 자르고 소문자화
whitespace Whitespace Tokenizer 오직 공백 문자만을 기준으로 단어를 분리 (대소문자 유지)
stop Lowercase Tokenizer
+ Stop Filter
Simple 분석기에 영어 기본 불용어(Stopwords) 제거 필터 추가
keyword Keyword Tokenizer 입력된 문자열 전체를 단 하나의 토큰으로 취급 (분석 생략)

4. 사용자 정의 커스텀 분석기 (Custom Analyzer) 구축

비즈니스 요구사항에 따라 내장 분석기만으로 부족할 때, 사용자가 직접 토크나이저와 토큰 필터를 조합하여 나만의 Custom Analyzer를 정의할 수 있다.

커스텀 분석기는 인덱스의 settings.analysis 블록에 정의하여 생성한다.

4.1 커스텀 분석기 인덱스 생성 예제

  • 토크나이저: whitespace
  • 토큰 필터: lowercase + 사용자 정의 불용어 필터(my_stop)
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/my_analyzer?pretty' -d '
{
  "settings": {
    "analysis": {
      "analyzer": {
        "my_analyzer": {
          "tokenizer": "whitespace",
          "filter": ["lowercase", "my_stop"]
        }
      },
      "filter": {
        "my_stop": {
          "type": "stop",
          "stopwords": ["quick", "lazy", "over", "dog"]
        }
      }
    }
  }
}'

4.2 생성한 커스텀 분석기 테스트

위에서 생성한 my_analyzer를 지정하여 _analyze API를 호출해 보자:

curl -H 'Content-Type: application/json' -X GET 'localhost:9200/my_analyzer/_analyze?pretty' -d '
{
  "analyzer": "my_analyzer",
  "text": "The 2 QUICK Brown-Foxes jumped over the lazy dog bone."
}'
/* 최종 추출된 텀 목록 */
{
  "tokens": [
    { "token": "the", ... },
    { "token": "2", ... },
    { "token": "brown-foxes", ... },
    { "token": "jumped", ... },
    { "token": "the", ... },
    { "token": "bone.", ... }
  ]
}
  • 기본 불용어인 the는 우리가 정의한 my_stop에 없으므로 유지되었다.
  • 대신 우리가 지정한 커스텀 불용어("quick", "lazy", "over", "dog")는 완벽하게 필터링되어 제외된 것을 확인할 수 있다.

마치며

이번 글에서는 Elasticsearch 검색 품질을 좌우하는 핵심 엔진인 분석기(Analyzer)의 3단계 파이프라인, _analyze API를 통한 실시간 토큰 검증, 그리고 5대 내장 분석기와 커스텀 분석기 제작법을 살펴보았다.

  • 검색이 의도대로 동작하지 않을 때는 항상 _analyze API를 사용해 입력된 데이터가 실제로 어떤 텀(Term)으로 쪼개져 인덱스에 들어갔는지 확인하는 것이 트러블슈팅의 첫걸음이다.
  • 한국어 검색의 경우 추후 nori 같은 한국어 형태소 분석기 플러그인을 Custom Analyzer에 얹어 사용하는 것이 일반적이다.
[광고 영역] AdSense Bottom Unit Slot