인덱스 템플릿 생성 또는 업데이트 API

인덱스 템플릿 생성 또는 업데이트 API (Create Or Update Index Template API)

1.0에서 도입되었어요. Create or Update Index Template API로 미리 정의된 매핑과 설정을 가진 인덱스를 만들고, 기존 인덱스 템플릿을 업데이트할 수 있어요.

출처: 문서

본문

엔드포인트 (Endpoints)

PUT _index_template/{template-name}
POST _index_template/{template-name}

경로 파라미터 (Path parameters)

파라미터	데이터 타입	설명
template-name	String	인덱스 템플릿의 이름이에요.

쿼리 파라미터 (Query parameters)

다음 선택 쿼리 파라미터를 지원해요.

파라미터	데이터 타입	설명
create	Boolean	`true`이면 API가 기존 인덱스 템플릿을 교체하거나 업데이트할 수 없어요. 기본값은 `false`예요.
cluster_manager_timeout	Time	클러스터 매니저 노드에 연결하기 위해 기다리는 시간이에요. 기본값은 `30s`예요.

요청 본문 필드 (Request body fields)

요청 본문에서 다음 옵션을 사용해 인덱스 템플릿을 사용자 지정할 수 있어요.

파라미터	타입	설명
index_patterns	String array	템플릿 생성 중에 만들어지는 데이터 스트림과 인덱스의 이름과 일치하는 와일드카드 표현의 배열이에요. 필수예요.
composed_of	String array	컴포넌트 템플릿 이름의 순서 있는 목록이에요. 이 템플릿들은 지정된 순서대로 병합돼요. 자세한 내용은 여러 컴포넌트 템플릿 사용을 참고하세요. 선택 사항이에요.
data_stream	Object	사용하면 요청이 템플릿을 기반으로 데이터 스트림과 backing index를 만들어요. 이 설정은 일치하는 인덱스 템플릿을 필요로 해요. `hidden` 설정과 함께 사용할 수도 있는데, `true`로 설정하면 데이터 스트림 backing index를 숨겨요. 선택 사항이에요.
_meta	Object	인덱스 템플릿에 대한 세부 정보를 제공하는 선택 메타데이터예요. 선택 사항이에요.
priority	Integer	새 인덱스나 데이터 스트림을 만들 때 어떤 인덱스 템플릿이 우선하는지 결정하는 숫자예요. OpenSearch는 가장 높은 priority를 가진 템플릿을 선택해요. priority가 주어지지 않으면 템플릿은 `0`이 할당되는데, 이는 가장 낮은 우선순위를 뜻해요. 선택 사항이에요.
template	Object	인덱스의 `aliases`, `mappings`, 또는 `settings`를 포함하는 템플릿이에요. 자세한 내용은 템플릿을 참고하세요. 선택 사항이에요.
version	Integer	인덱스 템플릿을 관리하는 데 사용하는 버전 번호예요. 버전 번호는 OpenSearch가 자동으로 설정하지 않아요. 선택 사항이에요.
context	Object	(실험적) context 파라미터는 인덱스에 적용할 수 있는 사용 사례별 미리 정의된 템플릿을 제공해요. 템플릿에 선언된 모든 설정과 매핑 중에서 context 템플릿이 가장 높은 우선순위를 가져요. 자세한 내용은 index-context를 참고하세요.

템플릿 (Template)

요청 본문의 template 옵션과 함께 다음 객체를 사용할 수 있어요.

alias

템플릿과 연결할 별칭을 키로 하는 이름이에요. 요청 본문에 template 옵션이 있으면 필수예요. 이 옵션은 여러 별칭을 지원해요.

객체 본문에는 다음 선택 별칭 파라미터가 들어 있어요.

파라미터	데이터 타입	설명
filter	Query DSL object	별칭이 접근할 수 있는 문서 수를 제한하는 쿼리예요.
index_routing	String	인덱싱 작업을 특정 샤드로 라우팅하는 값이에요. 지정하면 인덱싱 작업의 라우팅 값을 덮어써요.
is_hidden	Boolean	`true`이면 별칭이 숨겨져요. 기본값은 `false`예요. 모든 별칭 인덱스는 이 설정에 대해 일치하는 값을 가져야 해요.
is_write_index	Boolean	`true`이면 인덱스가 별칭의 쓰기 인덱스예요. 기본값은 `false`예요.
routing	String	인덱스와 검색 작업을 특정 샤드로 라우팅하는 데 사용하는 값이에요.
search_routing	String	특정 검색 작업을 특정 샤드로 쓰기 위해 사용하는 값이에요. 지정하면 검색 작업의 라우팅 값을 덮어써요.

mappings

인덱스에 존재하는 필드 매핑이에요. 자세한 내용은 Mappings and field types를 참고하세요. 선택 사항이에요.

settings

인덱스의 모든 구성 옵션이에요. 자세한 내용은 Index settings를 참고하세요.

예제 요청 (Example requests)

다음 예제들은 Create or Update Index Template API를 사용하는 법을 보여줘요.

인덱스 별칭이 있는 인덱스 템플릿 (Index template with index aliases)

다음 예제 요청은 템플릿에 인덱스 별칭을 포함해요.

일치하는 여러 템플릿 사용 (Using multiple matching templates)

새 인덱스나 데이터 스트림의 이름과 일치하는 인덱스 템플릿이 여러 개라면, 가장 높은 priority를 가진 템플릿이 사용돼요. 예를 들어 다음 두 요청은 서로 다른 priority를 가진 인덱스 템플릿을 만들어요.

첫 번째 요청은 h로 시작하는 인덱스 이름과 일치하는 priority 0 템플릿을 만들어요.

PUT /_index_template/template_one
{
  "index_patterns" : ["h*"],
  "priority" : 0,
  "template": {
    "settings" : {
      "number_of_shards" : 1,
      "number_of_replicas": 0
    },
    "mappings" : {
      "_source" : { "enabled" : false }
    }
  }
}

두 번째 요청은 ha로 시작하는 더 좁은 인덱스 이름 집합과 일치하는 priority 1 템플릿을 만들어요.

PUT /_index_template/template_two
{
  "index_patterns" : ["ha*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    },
    "mappings" : {
      "_source" : { "enabled" : true }
    }
  }
}

ha로 시작하는 인덱스에는 _source가 활성화돼요. template_two만 적용되기 때문에 이 인덱스는 프라이머리 샤드 2개와 복제본 1개를 가지게 돼요.

같은 priority를 가진 겹치는 인덱스 패턴은 허용되지 않아요. 동일한 priority를 가진 기존 인덱스 템플릿과 일치하는 템플릿을 만들려 하면 오류가 발생해요.

템플릿 버전 지정 추가 (Adding template versioning)

다음 예제 요청은 인덱스 템플릿에 버전 번호를 추가해서 외부 시스템이 템플릿을 더 쉽게 관리하도록 해요.

템플릿 메타데이터 추가 (Adding template metadata)

다음 예제 요청은 _meta 파라미터로 인덱스 템플릿에 메타데이터를 추가해요. 모든 메타데이터는 클러스터 상태에 저장돼요.

데이터 스트림 정의 (Data stream definition)

다음 예제 요청처럼 인덱스 템플릿을 데이터 스트림에 사용하려면 data_stream 객체를 포함하세요.

여러 컴포넌트 템플릿 사용 (Using multiple component templates)

composed_of 필드로 여러 컴포넌트 템플릿을 사용하면, 컴포넌트 템플릿이 지정된 순서대로 병합돼요. 그다음 컴포넌트의 상위 인덱스 템플릿에서 나온 모든 매핑, 설정, 별칭이 병합돼요. 마지막으로 인덱스 요청에 추가된 구성 옵션이 병합돼요.

다음 예제에서 my-index-*와 일치하는 인덱스는 병합된 프라이머리 샤드 2개를 가져요. composed_of 배열의 순서를 뒤집으면 인덱스는 프라이머리 샤드 1개를 가지게 돼요.

먼저 프라이머리 샤드 1개를 설정하는 컴포넌트 템플릿을 만들어요.

PUT /_component_template/template_with_1_shard
{
  "template": {
    "settings": {
      "index.number_of_shards": 1
    }
  }
}

다음으로 프라이머리 샤드 2개를 설정하는 컴포넌트 템플릿을 만들어요.

PUT /_component_template/template_with_2_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

마지막으로 두 컴포넌트 템플릿을 순서대로 구성하는 인덱스 템플릿을 만들어요.

PUT /_index_template/composed-template
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["template_with_1_shard", "template_with_2_shards"]
}

dynamic_templates와 _meta 같은 매핑 정의와 루트 옵션에는 재귀적 병합이 사용돼요. 즉 앞선 컴포넌트에 _meta 블록이 있으면, 새 _meta 항목이 인덱스의 메타데이터 끝에 추가돼요. 기존 키를 가진 항목은 덮어써져요.

필요한 권한 (Required permissions)

Security plugin을 사용한다면 indices:admin/index_template/put 권한이 있는지 확인하세요.

더 알아보기 (Learn more)

OpenSearch 공식 문서