본문 바로가기
WIKI 기술 지식 베이스

Mappings

원문 보기 위키 갱신

출처: 문서

본문

매핑

매핑은 OpenSearch에게 문서와 그 필드를 어떻게 저장하고 인덱싱할지 알려줘요. 각 필드의 데이터 타입을 지정하면(예: year를 date로) 저장과 쿼리를 더 효율적으로 만들 수 있어요.

동적 매핑은 새로운 데이터와 필드를 자동으로 추가해 주지만, 명시적 매핑을 사용하는 것이 권장돼요. 명시적 매핑을 사용하면 정확한 구조와 데이터 타입을 미리 정의할 수 있어요. 이는 특히 대용량 데이터셋이나 대량 인덱싱 작업에서 데이터 일관성을 유지하고 성능을 최적화하는 데 도움이 돼요.

예를 들어, 명시적 매핑을 사용하면 동적 매핑이 둘 다 정수로 해석해 버리는 대신, year는 텍스트로, age는 정수로 처리되도록 보장할 수 있어요.

매핑 구조와 개념

매핑을 만드는 방법을 배우기 전에, 매핑이 어떻게 구조화되어 있는지 그리고 이 문서 전반에서 사용되는 주요 용어를 이해하는 것이 중요해요.

매핑 구조와 예제

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
          }
        }
      }
    }
  }
}

{% include copy-curl.html %}

주요 용어

  • 매핑(Mappings): 인덱스의 전체 스키마 정의예요.
  • 프로퍼티(Properties): 매핑 안에 있는 모든 필드 정의를 담는 컨테이너예요.
  • 필드(Field): 개별 데이터 요소예요(예: title 또는 year).
  • 필드 타입(Field type): 필드 데이터가 어떻게 저장되고 인덱싱되는지 정의해요(예: text, integer, date). 자세한 내용은 지원되는 필드 타입을 참고하세요.
  • 매핑 파라미터(Mapping parameters): 필드 동작을 수정하는 설정 옵션이에요(예: analyzer, coerce, format). 자세한 내용은 매핑 파라미터를 참고하세요.

명시적 매핑

어떤 필드 데이터 타입을 사용해야 할지 정확히 알고 있다면, 다음 예제 요청처럼 인덱스를 생성할 때 요청 본문에 타입을 지정할 수 있어요:

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

{% include copy-curl.html %}

기존 필드의 매핑은 변경할 수 없어요. 필드의 매핑 파라미터만 수정할 수 있어요. {: .note}

기존 인덱스나 데이터 스트림에 매핑을 추가하려면, 다음 예제 요청처럼 PUT 또는 POST HTTP 메서드를 사용해 _mapping 엔드포인트로 요청을 보내면 돼요:

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

{% include copy-curl.html %}

Mapping API에 대한 자세한 내용은 매핑 업데이트를 참고하세요.

동적 매핑

문서를 인덱싱할 때 OpenSearch는 동적 매핑을 사용해 새로운 필드를 자동으로 감지하고 추가할 수 있어요. 이 동작은 필드 타입을 미리 정의하는 명시적 매핑과는 달라요.

동적 매핑 규칙

인덱싱 중에 새로운 필드를 만나면 OpenSearch는 다음 규칙에 따라 필드 타입을 결정해요:

JSON 데이터 타입 OpenSearch 필드 타입 설명
null 필드가 추가되지 않음 null 필드는 인덱싱하거나 검색할 수 없어요. 필드가 null로 설정되면 OpenSearch는 해당 필드에 값이 없는 것처럼 동작해요.
true 또는 false boolean 필드 OpenSearch는 true와 false를 불리언 값으로 받아들여요. 빈 문자열은 false와 같아요.
Double (예: 1.5) float 필드 유한한 값으로 제한되는 단정밀도 32비트 IEEE 754 부동 소수점 숫자예요. JSON 부동 소수점 숫자는 이 타입으로 매핑돼요.
Long (예: 1) long 필드 부호 있는 64비트 숫자예요. JSON 정수는 이 타입으로 매핑돼요.
Object ({}) object 필드 객체는 표준 JSON 객체로, 자체적인 필드와 매핑을 가질 수 있어요. 예를 들어, movies 객체는 title, year, director 같은 추가 속성을 가질 수 있어요.
Array ([]) 배열에서 첫 번째 null이 아닌 값에 따라 달라짐 OpenSearch에는 별도의 배열 데이터 타입이 없어요. 배열은 필드에 연결된, 동일한 데이터 타입(예: 정수 또는 문자열) 값들의 집합으로 표현돼요. 인덱싱할 때 필드에 여러 값을 전달할 수 있고, OpenSearch는 이를 배열로 취급해요. 빈 배열은 유효하며 요소가 0개인 배열 필드로 인식돼요---값이 없는 필드가 아니에요.
String ("") keyword 서브필드를 가진 text 필드, 또는 date 필드, 또는 숫자 필드 문자들로 이루어진 연속이에요. 기본적으로 문자열은 keyword 서브필드를 가진 text 필드로 매핑돼요. 하지만 문자열이 날짜 형식과 일치하면(날짜 감지가 활성화된 경우) date 필드가 돼요. 숫자 감지가 활성화되어 있고 문자열이 숫자를 나타낸다면, 그에 맞는 숫자 필드 타입으로 매핑돼요.

자동으로 감지되는 필드 타입은 이것들뿐이에요. 나머지 모든 필드 타입은 명시적으로 매핑해야 해요.

동적 템플릿

동적 템플릿은 OpenSearch가 동적으로 추가하는 필드에 대한 커스텀 매핑을 정의해요. 템플릿은 감지된 데이터 타입, 이름, 또는 경로를 기준으로 필드를 선택하고, 지정한 매핑을 적용해요. 자세한 내용은 동적 템플릿을 참고하세요.

동적 매핑 설정

OpenSearch는 새로운 필드를 처리할 때 동적 매핑이 어떻게 동작하는지 제어할 수 있는 여러 설정을 제공해요.

날짜 감지

기본적으로 OpenSearch는 날짜 형식의 문자열을 자동으로 감지해서 date 필드를 만들어요. date_detection이 활성화되어 있으면(기본값), 새로운 문자열 필드를 dynamic_date_formats에 지정된 날짜 패턴과 대조해서 확인해요. 일치하는 패턴을 찾으면 해당 형식을 가진 새로운 date 필드가 생성돼요.

dynamic_date_formats의 기본값은 다음과 같아요:

["strict_date_optional_time", "yyyy/MM/dd HH:mm:ss Z||yyyy/MM/dd Z"]

다음 예제 요청을 실행하면 create_date 필드가 yyyy/MM/dd HH:mm:ss Z||yyyy/MM/dd Z 형식의 date 필드로 자동 매핑돼요:

PUT sample-index/_doc/1
{
  "create_date": "2025/05/26"
}

{% include copy-curl.html %}

date_detection을 false로 설정하면 자동 날짜 감지를 비활성화할 수 있어요:

PUT sample-index
{
  "mappings": {
    "date_detection": false
  }
}

{% include copy-curl.html %}

날짜 감지가 비활성화되면, 날짜 형식의 문자열은 대신 text 필드로 매핑돼요.

자체적인 dynamic_date_formats를 지정하면 감지에 사용되는 날짜 패턴을 커스터마이즈할 수 있어요:

PUT sample-index
{
  "mappings": {
    "dynamic_date_formats": ["MM/dd/yyyy", "dd-MM-yyyy"]
  }
}

{% include copy-curl.html %}

숫자 감지

JSON은 기본적인 숫자 데이터 타입을 지원하지만, 일부 애플리케이션은 숫자를 문자열로 보낼 수 있어요. numeric_detection이 활성화되어 있으면 OpenSearch는 숫자 문자열을 자동으로 감지해서 숫자 필드로 매핑할 수 있어요.

숫자 감지는 기본적으로 비활성화되어 있어요. 숫자 필드에는 명시적 매핑을 사용하는 방식이 권장돼요. {: .note}

숫자 감지를 활성화하려면 다음 요청을 보내세요:

PUT sample-index
{
  "mappings": {
    "numeric_detection": true
  }
}

{% include copy-curl.html %}

그다음 숫자 필드가 포함된 문서를 인덱스에 인덱싱하세요:

PUT sample-index/_doc/1
{
  "price": "19.99",
  "quantity": "5"
}

{% include copy-curl.html %}

숫자 감지가 활성화되어 있으면:

  • price 필드는 float 필드로 매핑돼요
  • quantity 필드는 long 필드로 매핑돼요

매핑 조회하기

하나 이상의 인덱스에 대한 모든 매핑을 가져오려면 다음 요청을 사용하세요:

GET {index}/_mapping

{% include copy-curl.html %}

앞의 요청에서 <index>는 인덱스 이름이거나 쉼표로 구분된 인덱스 이름 목록일 수 있어요.

모든 인덱스의 매핑을 가져오려면 다음 요청을 사용하세요:

GET _mapping

{% include copy-curl.html %}

특정 필드의 매핑을 가져오려면 인덱스 이름과 필드 이름을 제공하세요:

GET _mapping/field/{fields}
GET /{index}/_mapping/field/{fields}

<index>와 <fields>는 모두 하나의 값 또는 쉼표로 구분된 목록으로 지정할 수 있어요. 예를 들어, 다음 요청은 sample-index1에서 year와 age 필드에 대한 매핑을 가져와요:

GET sample-index1/_mapping/field/year,age

{% include copy-curl.html %}

응답에는 지정된 필드가 포함되어 있어요:

{
  "sample-index1" : {
    "mappings" : {
      "year" : {
        "full_name" : "year",
        "mapping" : {
          "year" : {
            "type" : "text"
          }
        }
      },
      "age" : {
        "full_name" : "age",
        "mapping" : {
          "age" : {
            "type" : "integer"
          }
        }
      }
    }
  }
}

자세한 내용은 Get Index API를 참고하세요.

예제

다음 예제는 다양한 시나리오에서 OpenSearch 매핑을 실제로 활용하는 방법을 보여줘요.

잘못된 형식의 IP 주소 무시하기

다음 예제는 ip 데이터 타입을 준수하지 않는 잘못된 형식의 IP 주소가 포함된 문서를 OpenSearch가 무시하도록 지정하는 매핑을 만드는 방법을 보여줘요. ignore_malformed 파라미터를 true로 설정하면 이렇게 할 수 있어요.

ip 매핑이 있는 인덱스를 만들려면 PUT 요청을 사용하세요:

PUT /test-index
{
  "mappings" : {
    "properties" :  {
      "ip_address" : {
        "type" : "ip",
        "ignore_malformed": true
      }
    }
  }
}

{% include copy-curl.html %}

그다음 잘못된 형식의 IP 주소가 포함된 문서를 추가하세요:

PUT /test-index/_doc/1
{
  "ip_address" : "malformed ip address"
}

{% include copy-curl.html %}

인덱스를 쿼리하면 ip_address 필드는 무시돼요. 다음 요청을 사용해서 인덱스를 쿼리할 수 있어요:

GET /test-index/_search

{% include copy-curl.html %}

응답을 보면 문서가 성공적으로 인덱싱되었지만, 잘못된 형식의 IP 주소 필드가 _ignored 배열에 나열되어 있는 걸 알 수 있어요:

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "test-index",
        "_id": "1",
        "_score": 1,
        "_ignored": [
          "ip_address"
        ],
        "_source": {
          "ip_address": "malformed ip address"
        }
      }
    ]
  }
}

문자열 필드를 text 및 keyword 타입으로 매핑하기

모든 문자열 필드를 text와 keyword 타입 둘 다로 매핑하는 동적 템플릿이 있는 movies1이라는 인덱스를 만들려면 다음 요청을 사용할 수 있어요:

PUT movies1
{
  "mappings": {
    "dynamic_templates": [
      {
        "strings": {
          "match_mapping_type": "string",
          "mapping": {
            "type": "text",
            "fields": {
              "keyword": {
                "type":  "keyword",
                "ignore_above": 256
              }
            }
          }
        }
      }
    ]
  }
}

{% include copy-curl.html %}

이 동적 템플릿은 문서에 있는 모든 문자열 필드가 전체 텍스트 text 타입과 keyword 타입 둘 다로 인덱싱되도록 보장해요.

매핑 파라미터

매핑 파라미터는 인덱스 필드의 동작을 구성하는 데 사용돼요. 사용 가능한 모든 매핑 파라미터에 대한 자세한 내용은 매핑 파라미터를 참고하세요.

메타데이터 필드

OpenSearch는 _source, _id, _index 같은 여러 메타데이터 필드를 각 문서마다 자동으로 관리해요. 사용 가능한 모든 메타데이터 필드와 설정 옵션에 대한 내용은 메타데이터 필드를 참고하세요.

매핑 제한 설정

OpenSearch는 매핑 폭발을 방지하고 매핑 증가를 제어하는 여러 설정을 제공해요. 이 설정들은 클러스터 성능을 유지하고, 과도하게 많은 필드가 생성되면서 생기는 메모리 문제를 예방하는 데 도움이 돼요.

기본값과 유효 범위를 포함한 모든 매핑 제한 설정에 대한 자세한 내용은 매핑 제한 설정을 참고하세요.

관련 문서

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.