OpenSearch 매핑

OpenSearch 매핑 (Mappings)

**매핑(mappings)**은 OpenSearch가 문서와 필드를 어떻게 저장·인덱싱할지 알려 주는 설정이에요. 각 필드의 데이터 타입을 지정할 수 있는데, 예를 들어 year 필드를 date 타입으로 선언하면 저장과 쿼리가 훨씬 효율적이 돼요. 동적 매핑이 새 데이터와 필드를 자동으로 추가해 주긴 하지만, 명시적 매핑을 쓰는 게 권장돼요. 명시적 매핑으로 구조와 데이터 타입을 미리 정의하면 데이터 일관성을 유지하고 대용량 데이터나 대량 인덱싱 작업에서 성능을 최적화할 수 있어요.

출처: https://docs.opensearch.org/latest/mappings/

매핑 구조와 핵심 용어

OpenSearch 매핑은 계층적인 JSON 구조를 따라요. 아래 예제는 text·date 필드를 매핑 파라미터와 함께 쓰고, 자체 프로퍼티를 가진 중첩 director 객체까지 담고 있어요.

PUT /movies
{
  "mappings": {                    // Overall mappings object
    "properties": {                // Properties container
      "title": {                   // Field name
        "type": "text",            // Field type
        "analyzer": "standard"     // Mapping parameter
      },
      "year": {                    // Field name
        "type": "date",            // Field type
        "format": "yyyy"           // Mapping parameter
      },
      "director": {                // Field name (object type)
        "type": "object",          // Field type
        "properties": {            // Properties container for nested fields
          "name": {                // Field name (nested)
            "type": "text"         // Field type
          }
        }
      }
    }
  }
}

핵심 용어를 정리하면 이래요.

Mappings: 인덱스의 전체 스키마 정의
Properties: 매핑 안의 모든 필드 정의를 담는 컨테이너
Field: 개별 데이터 요소 (title, year 같은 것)
Field type: 필드 데이터가 어떻게 저장·인덱싱되는지 정의 (text, integer, date 등)
Mapping parameters: 필드 동작을 수정하는 설정 옵션 (analyzer, coerce, format 등)

명시적 매핑 (Explicit mapping)

사용할 필드 타입을 정확히 안다면 인덱스 생성 요청 본문에 지정할 수 있어요.

PUT sample-index1
{
  "mappings": {
    "properties": {
      "year":    { "type" : "text" },
      "age":     { "type" : "integer" },
      "director":{ "type" : "text" }
    }
  }
}

이미 존재하는 필드의 매핑 자체는 바꿀 수 없고, 필드의 매핑 파라미터만 수정할 수 있어요. 기존 인덱스나 데이터 스트림에 매핑을 추가하려면 _mapping 엔드포인트에 PUT이나 POST를 보내면 돼요.

POST sample-index1/_mapping
{
  "properties": {
    "year":    { "type" : "text" },
    "age":     { "type" : "integer" },
    "director":{ "type" : "text" }
  }
}

동적 매핑 (Dynamic mapping)

문서를 인덱싱할 때 OpenSearch는 동적 매핑으로 새 필드를 자동 감지·추가할 수 있어요. 새 필드를 만났을 때 적용되는 규칙은 다음과 같아요.

null → 필드가 추가되지 않아요 (인덱싱·검색 불가)
true/false → boolean 필드 (빈 문자열은 false와 같음)
Double (예: 1.5) → float 필드
Long (예: 1) → long 필드
Object ({}) → object 필드
Array ([]) → 배열의 첫 번째 null이 아닌 값에 따라 결정
String ("") → 기본적으로 keyword 하위 필드를 가진 text 필드. 날짜 형식과 맞으면 date, 숫자 감지가 켜져 있고 숫자면 해당 숫자 타입이 돼요.

이것들이 자동 감지되는 전체 필드 유형이고, 나머지는 반드시 명시적으로 매핑해야 해요.

동적 템플릿 (Dynamic templates)

동적 템플릿은 데이터 타입, 필드 이름, 필드 경로를 기준으로 동적으로 추가되는 필드에 커스텀 매핑을 정의하는 방법이에요. 예를 들어 status로 시작하는 필드를 short 타입으로 자동 매핑할 수 있어요.

PUT index
{
  "mappings": {
    "dynamic_templates": [
        {
          "fields": {
            "mapping": {
              "type": "short"
            },
            "match_mapping_type": "string",
            "path_match": "status*"
          }
        }
    ]
  }
}

이 설정은 이름이 status로 시작하는 필드(예: status_code)를, 인덱싱 시 값이 문자열이면 short 타입으로 동적 매핑해요.

OpenSearch 매핑