인덱스 매핑 생성·갱신 API

인덱스 매핑 생성·갱신 API (Create or Update Index Mappings API)

1.0부터 도입되었어요.

이 API를 사용해 기존 인덱스에 새 필드를 도입하거나 기존 필드의 검색 설정을 수정할 수 있어요. 이 작업은 인덱스를 처음부터 다시 생성하지 않고도 인덱스 스키마를 발전시킬 수 있게 해 줘요.

이미 인덱싱된 데이터가 있는 필드의 매핑이나 필드 타입은 이 작업으로 변경할 수 없어요. 기존 필드의 타입을 변경하면 이전에 인덱싱된 데이터가 새 매핑과 호환되지 않을 위험이 있어요. 기존 필드의 타입을 변경해야 한다면 원하는 매핑으로 새 인덱스를 만든 다음 Reindex 작업으로 원본 인덱스의 문서를 복사해요. 리인덱싱 중 다운타임을 피하려면 aliases를 사용할 수 있어요. 자세한 내용은 기존 필드의 타입 변경을 참고해요.

출처: 문서

본문

엔드포인트

POST /{index}/_mapping
PUT  /{index}/_mapping

경로 파라미터

사용할 수 있는 경로 파라미터는 아래 표와 같아요.

파라미터 필수 데이터 타입 설명
index 필수 String 갱신할 인덱스의 이름이에요. 단일 인덱스 이름, 쉼표로 구분된 인덱스 이름 목록, 또는 와일드카드 표현식을 지정할 수 있어요. 모든 인덱스의 매핑을 갱신하려면 _all 또는 *을 사용해요.

쿼리 파라미터

사용할 수 있는 쿼리 파라미터는 아래 표와 같아요. 모든 쿼리 파라미터는 선택사항이에요.

파라미터 데이터 타입 설명 기본값
allow_no_indices Boolean 어떤 인덱스와도 일치하지 않는 와일드카드를 무시할지 여부를 지정해요. false이면 와일드카드가 어떤 인덱스와도 일치하지 않을 때 오류를 반환해요. true
cluster_manager_timeout String 클러스터 매니저 노드에 연결될 때까지 기다리는 시간이에요. 30s
expand_wildcards String 와일드카드 표현식이 확장될 수 있는 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. 유효한 값은 all(숨은 인덱스를 포함한 모든 인덱스 매치), open(열린 인덱스 매치), closed(닫힌 인덱스 매치), hidden(숨은 인덱스 매치 — open, closed, 또는 둘 다와 함께 사용해야 해요), none(와일드카드 표현식을 받지 않음). open
ignore_unavailable Boolean 누락되었거나 닫힌 인덱스를 무시할지 지정해요. true면 누락되거나 닫힌 인덱스가 응답에 포함되지 않아요. false
timeout String 응답을 기다리는 시간이에요. 시간 초과 전에 응답을 받지 못하면 요청이 실패하고 오류를 반환해요. 30s
write_index_only Boolean true이면 매핑이 대상의 현재 쓰기 인덱스에만 적용돼요. false

요청 본문 필드

사용할 수 있는 요청 본문 필드는 아래 표와 같아요.

필드 데이터 타입 설명
properties Object 필수예요. 인덱스 매핑의 필드와 그 타입을 정의해요. 각 필드는 이름, field data type, mapping parameters를 포함할 수 있어요.
dynamic String 새 필드가 동적으로 추가되는지 여부를 제어해요. 유효한 값은 true(새 필드 자동 추가), false(새 필드 무시), strict(매핑되지 않은 필드를 포함한 요청 거부)예요. 기본값은 true예요.

예시: 인덱스에 필드 추가

Create or Update Mappings API는 기존 인덱스가 필요해요. 다음 예제는 products 인덱스에 description과 price 필드를 추가해요:

PUT /products/_mapping
{
  "properties": {
    "description": {
      "type": "text"
    },
    "price": {
      "type": "float"
    }
  }
}

Get Mappings API로 매핑이 적용되었는지 확인할 수 있어요:

GET /products/_mapping

예시: 여러 인덱스 갱신

인덱스 이름을 쉼표로 구분한 목록을 지정하면 단일 요청으로 여러 인덱스에 매핑 갱신을 적용할 수 있어요. 다음 예제는 미국과 EU 지역 카탈로그에 currency와 tax_rate 필드를 추가해요:

PUT /products-us,products-eu/_mapping
{
  "properties": {
    "currency": {
      "type": "keyword"
    },
    "tax_rate": {
      "type": "float"
    }
  }
}

예시: 기존 객체 필드에 속성 추가

기존 object 필드에 새 내부 필드를 추가할 수 있어요. products 인덱스에 name 필드를 가진 manufacturer 객체가 이미 있다고 가정해 봐요. 다음 예제는 manufacturer 객체에 country 키워드 필드를 추가해요:

PUT /products/_mapping
{
  "properties": {
    "manufacturer": {
      "properties": {
        "country": {
          "type": "keyword"
        }
      }
    }
  }
}

매핑을 조회해 중첩 구조를 확인할 수 있어요:

GET /products/_mapping

응답:

{
  "products" : {
    "mappings" : {
      "properties" : {
        "description" : {
          "type" : "text"
        },
        "manufacturer" : {
          "properties" : {
            "country" : {
              "type" : "keyword"
            },
            "name" : {
              "type" : "text"
            }
          }
        },
        "price" : {
          "type" : "float"
        },
        "product_name" : {
          "type" : "text"
        }
      }
    }
  }
}

예시: 기존 필드에 멀티 필드 추가

Multi-fields는 같은 필드를 다양한 방식으로 인덱싱할 수 있게 해 줘요. 예를 들어 전체 텍스트 검색에 쓰이는 text 필드에 정렬이나 집계용 keyword 하위 필드를 둘 수 있어요. 다음 예제는 ignore_above를 256으로 설정한 product_name.keyword 하위 필드를 추가해서 제품명에 대한 정확 일치 필터링과 정렬을 가능하게 해요:

PUT /products/_mapping
{
  "properties": {
    "product_name": {
      "type": "text",
      "fields": {
        "keyword": {
          "type": "keyword",
          "ignore_above": 256
        }
      }
    }
  }
}

멀티 필드 구성을 확인할 수 있어요:

GET /products/_mapping

응답:

{
  "products" : {
    "mappings" : {
      "properties" : {
        "description" : {
          "type" : "text"
        },
        "manufacturer" : {
          "properties" : {
            "country" : {
              "type" : "keyword"
            },
            "name" : {
              "type" : "text"
            }
          }
        },
        "price" : {
          "type" : "float"
        },
        "product_name" : {
          "type" : "text",
          "fields" : {
            "keyword" : {
              "type" : "keyword",
              "ignore_above" : 256
            }
          }
        }
      }
    }
  }
}

예시: 지원되는 매핑 파라미터 변경

일부 mapping parameters는 Create or Update Mappings API로 기존 필드에 대해 갱신할 수 있어요. 예를 들어 키워드 필드의 ignore_above 값을 변경할 수 있어요. 다음 예제는 sku 필드의 ignore_above를 20에서 50으로 늘려 더 긴 제품 코드도 인덱싱할 수 있게 해요:

PUT /products/_mapping
{
  "properties": {
    "sku": {
      "type": "keyword",
      "ignore_above": 50
    }
  }
}

갱신된 파라미터 값을 확인할 수 있어요:

GET /products/_mapping

응답:

{
  "products" : {
    "mappings" : {
      "properties" : {
        "description" : {
          "type" : "text"
        },
        "manufacturer" : {
          "properties" : {
            "country" : {
              "type" : "keyword"
            },
            "name" : {
              "type" : "text"
            }
          }
        },
        "price" : {
          "type" : "float"
        },
        "product_name" : {
          "type" : "text",
          "fields" : {
            "keyword" : {
              "type" : "keyword",
              "ignore_above" : 256
            }
          }
        },
        "sku" : {
          "type" : "keyword",
          "ignore_above" : 50
        }
      }
    }
  }
}

예시: 별칭으로 필드 이름 바꾸기

필드 이름을 바꾸면 이전에 저장된 데이터가 새 이름으로 접근할 수 없게 되므로, 필드를 다른 방식으로 참조할 수 있게 alias 필드 타입을 사용해요. 다음 예제는 기존 product_id 필드를 가리키는 item_id 별칭을 만들어 두 이름 모두로 쿼리할 수 있게 해요:

PUT /products/_mapping
{
  "properties": {
    "item_id": {
      "type": "alias",
      "path": "product_id"
    }
  }
}

별칭이 생성되었는지 확인할 수 있어요:

GET /products/_mapping

응답:

{
  "products" : {
    "mappings" : {
      "properties" : {
        "description" : {
          "type" : "text"
        },
        "item_id" : {
          "type" : "alias",
          "path" : "product_id"
        },
        "manufacturer" : {
          "properties" : {
            "country" : {
              "type" : "keyword"
            },
            "name" : {
              "type" : "text"
            }
          }
        },
        "price" : {
          "type" : "float"
        },
        "product_id" : {
          "type" : "keyword"
        },
        "product_name" : {
          "type" : "text",
          "fields" : {
            "keyword" : {
              "type" : "keyword",
              "ignore_above" : 256
            }
          }
        },
        "sku" : {
          "type" : "keyword",
          "ignore_above" : 50
        }
      }
    }
  }
}

예시: 기존 필드의 타입 변경

이미 인덱싱된 데이터가 있는 필드의 필드 타입은 직접 변경할 수 없어요. 대신 올바른 매핑으로 새 인덱스를 만들고 Reindex API로 원본 인덱스의 문서를 복사해요.

다음 예제는 weight 필드를 integer에서 float로 변경해서 0.75 kg 같은 분수 값도 정확하게 저장할 수 있게 해요.

먼저 갱신된 필드 타입으로 새 인덱스를 만들어요:

PUT /products-v2
{
  "mappings": {
    "properties": {
      "product_name": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      },
      "price": {
        "type": "float"
      },
      "weight": {
        "type": "float"
      }
    }
  }
}

그런 다음 원본 인덱스의 데이터를 새 인덱스로 리인덱싱해요:

POST /_reindex
{
  "source": {
    "index": "products"
  },
  "dest": {
    "index": "products-v2"
  }
}

응답:

{
  "took" : 8,
  "timed_out" : false,
  "total" : 2,
  "updated" : 0,
  "created" : 2,
  "deleted" : 0,
  "batches" : 1,
  "version_conflicts" : 0,
  "noops" : 0,
  "retries" : {
    "bulk" : 0,
    "search" : 0
  },
  "throttled_millis" : 0,
  "requests_per_second" : -1.0,
  "throttled_until_millis" : 0,
  "failures" : [ ]
}

응답 예시

매핑 갱신이 성공하면 다음 응답을 반환해요:

{
  "acknowledged": true
}

응답 본문 필드

모든 응답 본문 필드는 아래 표와 같아요.

필드 데이터 타입 설명
acknowledged Boolean 클러스터의 관련 노드들이 요청을 승인했는지 여부를 나타내요.

필요한 권한

보안 플러그인을 사용한다면 다음 권한이 필요해요: indices:admin/mapping/put.

더 알아보기 (Learn more)