5장. 매핑과 필드 타입 — 스키마 없는 척하는 스키마

Elasticsearch는 "schemaless"를 표방하지만, 모든 인덱스에는 매핑이라는 스키마가 있습니다. 그리고 한 번 정한 필드 타입은 바꿀 수 없습니다 — 후회하기 전에 배우는 매핑 설계.

5.1 매핑이란 — 필드의 운명을 정하는 계약서

매핑(mapping)은 문서가 어떤 필드로 구성되고, 각 필드를 어떻게 저장·색인·검색할지 정의하는 메타데이터입니다. RDBMS의 DDL과 비슷하지만 결정적 차이가 있습니다: 스키마 위반 시 에러 대신 자동 추론이 일어나고, 타입 변경이 불가능하다는 점입니다.

# 명시적 매핑으로 인덱스 생성
PUT /products
{
  "mappings": {
    "properties": {
      "name":       { "type": "text" },      # 풀텍스트 검색 대상
      "sku":        { "type": "keyword" },   # 정확 매칭·집계용
      "price":      { "type": "scaled_float", "scaling_factor": 100 },
      "stock":      { "type": "integer" },
      "created_at": { "type": "date" },
      "tags":       { "type": "keyword" }
    }
  }
}

매핑이 결정하는 것들: 역색인에 들어갈지 / doc values(컬럼 스토어)를 만들지 / 어떤 analyzer를 거칠지 / term·range·풀텍스트 쿼리가 가능한지 / 정렬·집계가 가능한지 / 디스크·메모리를 얼마나 쓸지. 필드의 운명 전부입니다.

5.2 Dynamic 매핑 — 편리함의 청구서

매핑에 없는 새 필드가 들어오면? dynamic 파라미터가 처리 방식을 정합니다.

5.3 text vs keyword — 가장 흔한 실수

Elasticsearch에는 "string" 타입이 없습니다. 문자열은 text와 keyword라는 완전히 다른 두 타입으로 색인됩니다. 같은 문자열 "Quick Brown Fox"가 두 타입에서 어떤 운명을 맞는지 봅시다.

이 차이를 모르고 status 같은 enum 필드를 text로 만들면, 집계하는 순간 이런 에러를 만납니다.

# status가 text 타입일 때 terms 집계 시도
GET /orders/_search
{
  "size": 0,
  "aggs": { "by_status": { "terms": { "field": "status" } } }
}

# → 400 에러:
# "Text fields are not optimised for operations that require
#  per-document field data like aggregations and sorting...
#  Please use a keyword field instead."

5.4 Multi-fields — 한 데이터, 여러 색인

같은 데이터를 여러 방식으로 동시에 색인할 수 있습니다. 가장 흔한 실전 패턴입니다.

PUT /articles
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",                    # title        → 풀텍스트 검색
        "fields": {
          "keyword": {                      # title.keyword → 정렬·집계·정확매칭
            "type": "keyword",
            "ignore_above": 256            # 256자 초과는 keyword 색인 제외
          },
          "korean": {                       # title.korean  → 한국어 형태소 검색
            "type": "text", "analyzer": "nori"
          }
        }
      }
    }
  }
}

이 매핑에서 title은 실제로 3개의 색인을 갖습니다. dynamic 매핑이 문자열에 자동으로 만들어주는 것도 바로 text + fields.keyword 조합입니다 — 자동 생성된 인덱스에서 title.keyword로 집계할 수 있는 이유입니다.

5.5 주요 필드 타입 카탈로그

5.6 Object 배열의 함정 — 그리고 nested

객체 배열을 기본 object 타입으로 색인하면 검색 결과가 조용히 틀리는 유명한 함정이 있습니다. 에러도 없이, 매칭되면 안 되는 문서가 매칭됩니다.

세 가지 선택지를 정리하면:

• object (기본) — 구조화된 단일 객체엔 충분. 배열 + 항목 내 AND 조건에서만 함정 발동.
• nested — 배열 객체의 경계 보존. nested 쿼리 필수, 색인 비용 증가.
• flattened — 키가 동적으로 늘어나는 객체(사용자 정의 라벨 등)를 하나의 필드로 취급해 매핑 폭증 방지. 모든 값이 keyword로 취급되는 제약.

5.7 매핑은 변경 불가 — 무중단 reindex 전략

한 번 정한 필드의 타입은 바꿀 수 없습니다. 새 필드 추가나 multi-field 추가는 되지만, text → keyword 같은 타입 변경이나 analyzer 변경은 재색인(reindex)이 유일한 길입니다.

# ❌ 이미 text인 필드를 keyword로 바꾸려 하면
PUT /products/_mapping
{ "properties": { "status": { "type": "keyword" } } }

# → 400: mapper [status] cannot be changed from type [text] to [keyword]

그래서 운영의 정석은 처음부터 인덱스를 alias 뒤에 숨기는 것입니다. 클라이언트는 alias만 바라보게 하고, 매핑을 바꿀 일이 생기면 새 인덱스로 reindex한 뒤 alias를 원자적으로 스왑합니다.

# 무중단 reindex 3단계
# 1) 올바른 매핑으로 새 인덱스 생성
PUT /products_v2 { "mappings": { ... } }

# 2) 데이터 복사 (slices로 병렬화 가능)
POST /_reindex?slices=auto
{
  "source": { "index": "products" },
  "dest":   { "index": "products_v2" }
}

# 3) alias 원자적 스왑 — 다운타임 0
POST /_aliases
{
  "actions": [
    { "remove": { "index": "products",    "alias": "products_search" } },
    { "add":    { "index": "products_v2", "alias": "products_search" } }
  ]
}

✍️ 이해도 체크