인덱스 생성 API
인덱스 생성 API (Create Index API)
1.0에서 도입되었어요. Create Index API는 OpenSearch 클러스터에 새 인덱스를 만들어요.
Create Index API로 다음 인덱스 구성을 지정할 수 있어요.
- 샤드와 복제본 수 같은 인덱스 동작을 제어하는 인덱스 설정
- 인덱스에 저장된 문서의 필드 데이터 타입과 속성을 정의하는 필드 매핑
- 인덱스 조회를 위한 별칭(alias)을 제공하는 인덱스 별칭
출처: 문서
본문
엔드포인트 (Endpoints)
PUT /{index}
인덱스 이름 제한 (Index naming restrictions)
OpenSearch 인덱스에는 다음과 같은 이름 제한이 있어요.
- 모든 글자는 소문자여야 해요.
- 인덱스 이름은 밑줄(
_)이나 하이픈(-)으로 시작할 수 없어요. - 인덱스 이름에 공백, 쉼표, 그리고 다음 문자를 포함할 수 없어요:
:,",*,+,/,\,|,?,#,>,<
경로 파라미터 (Path parameters)
다음 표는 사용 가능한 경로 파라미터를 보여줘요.
| 파라미터 | 필수 | 데이터 타입 | 설명 |
|---|---|---|---|
| index | 필수 | String | 만들고 싶은 인덱스의 이름이에요. |
쿼리 파라미터 (Query parameters)
다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
| cluster_manager_timeout | String | 클러스터 매니저 노드에 연결하기 위해 기다리는 시간이에요. |
| timeout | String | 응답을 기다리는 시간이에요. 제한 시간이 지나기 전에 응답이 없으면 요청이 실패하고 오류를 반환해요. |
| wait_for_active_shards | Integer 또는 String 또는 NULL 또는 String | 작업을 진행하기 전에 활성화되어야 하는 샤드 복사본 수예요. all 또는 인덱스의 전체 샤드 수(number_of_replicas+1)까지의 양의 정수로 설정해요. 유효한 값은 다음과 같아요. - all : 모든 샤드가 활성화될 때까지 기다려요. |
요청 본문 필드 (Request body fields)
새 인덱스를 구성하기 위해 다음 요청 본문 필드를 포함할 수 있어요. 모든 요청 본문 필드는 선택 사항이에요.
| 필드 | 데이터 타입 | 설명 |
|---|---|---|
| settings | Object | 인덱스 수준의 설정이에요. 인덱스 설정 목록은 Index settings를 참고하세요. 선택 사항이에요. |
| settings.index.number_of_shards | Integer | 인덱스의 프라이머리 샤드 수예요. 기본값은 1이에요. 선택 사항이에요. |
| settings.index.number_of_replicas | Integer | 각 프라이머리 샤드의 복제본 샤드 수예요. 기본값은 1이에요. 선택 사항이에요. |
| settings.number_of_shards | Integer | index 접두사 없이 프라이머리 샤드 수를 지정하는 간단한 문법이에요. 선택 사항이에요. |
| settings.number_of_replicas | Integer | index 접두사 없이 복제본 샤드 수를 지정하는 간단한 문법이에요. 선택 사항이에요. |
| mappings | Object | 인덱스에 있는 문서의 필드 매핑이에요. 각 필드의 데이터 타입과 속성을 정의해요. 자세한 내용은 Mappings를 참고하세요. 선택 사항이에요. |
| mappings.properties | Object | 문서의 필드와 데이터 타입을 정의해요. 각 키는 필드 이름이고 각 값은 필드 정의 객체예요. 선택 사항이에요. |
| aliases | Object | 인덱스의 인덱스 별칭이에요. 각 키는 별칭 이름이고 각 값은 별칭 정의 객체예요. 자세한 내용은 Index aliases를 참고하세요. 선택 사항이에요. |
참고: settings 섹션 안에 index 섹션을 명시적으로 지정하지 않아도 돼요. 대신 간단한 문법을 사용할 수 있어요.
예제: 기본 인덱스 만들기 (Example: Creating a basic index)
보통 빈 인덱스를 명시적으로 만들 필요는 없어요. OpenSearch는 존재하지 않는 인덱스에 문서를 인덱싱하면 인덱스를 자동으로 만들어요. 하지만 데이터를 인덱싱하기 전에 특정 설정, 매핑, 별칭을 구성하고 싶다면 인덱스를 명시적으로 만드는 게 유용해요.
다음 예제 요청은 설정, 매핑, 별칭 없이 sample-index라는 인덱스를 만들어요.
예제: 설정이 있는 인덱스 만들기 (Example: Creating an index with settings)
다음 예제 요청은 샤드와 복제본 수에 대한 특정 설정으로 books라는 인덱스를 만들어요.
예제: 간단한 설정으로 인덱스 만들기 (Example: Creating an index with simplified settings)
다음 예제 요청은 index 접두사가 없는 간단한 설정 문법으로 books-simplified라는 인덱스를 만들어요.
예제: 매핑이 있는 인덱스 만들기 (Example: Creating an index with mappings)
다음 예제 요청은 필드 매핑이 있는 employees라는 인덱스를 만들어요.
예제: 별칭이 있는 인덱스 만들기 (Example: Creating an index with aliases)
다음 예제 요청은 필터링된 별칭을 포함해 두 개의 별칭을 가진 orders라는 인덱스를 만들어요.
예제 응답 (Example response)
create index 요청이 성공하면 OpenSearch는 다음 응답을 반환해요.
{
"acknowledged": true,
"shards_acknowledged": true,
"index": "books"
}
응답 본문 필드 (Response body fields)
다음 표는 모든 응답 본문 필드를 보여줘요.
| 필드 | 데이터 타입 | 설명 |
|---|---|---|
| acknowledged | Boolean | 인덱스가 클러스터에서 성공적으로 만들어졌는지 여부예요. true는 새 인덱스로 클러스터 상태가 성공적으로 업데이트되었다는 뜻이에요. false는 클러스터 상태가 업데이트되기 전에 요청이 제한 시간을 넘겼다는 뜻인데, 인덱스는 곧 만들어질 가능성이 높아요. |
| shards_acknowledged | Boolean | wait_for_active_shards 설정이 지정한 샤드 복사본 수가 작업이 제한 시간을 넘기기 전에 활성화되었는지 여부예요. true는 목표 샤드 복사본 수가 활성화되었다는 뜻이고, false는 클러스터 상태가 성공적으로 업데이트되었는지와 무관하게(acknowledged가 true여도) 작업이 제한 시간을 넘길 때까지 목표 샤드 복사본 수가 활성화되지 않았다는 뜻이에요. |
| index | String | 새로 만들어진 인덱스의 이름이에요. |
활성 샤드 기다리기 (Wait for active shards)
기본적으로 create index 작업은 각 샤드의 프라이머리 복사본이 시작된 후 또는 요청이 제한 시간을 넘길 때만 클라이언트에 응답을 반환해요. 응답 필드로 작업 결과를 파악할 수 있어요.
acknowledged 필드는 클러스터 상태에서 인덱스가 성공적으로 만들어졌는지 여부를 나타내요. shards_acknowledged 필드는 제한 시간 전에 목표 샤드 복사본 수가 활성화되었는지 여부를 나타내요. 작업이 제한 시간을 넘기면 두 필드 모두 false일 수 있지만, 인덱스 생성은 여전히 성공할 수 있어요.
acknowledged가 false면 클러스터 상태 업데이트가 제한 시간을 넘긴 것이지만 인덱스는 곧 만들어질 가능성이 높아요. shards_acknowledged가 false면 클러스터 상태가 성공적으로 업데이트되었는지와 무관하게 제한 시간 전에 목표 샤드 복사본 수가 활성화되지 않은 것이에요.
프라이머리 샤드만 기다리는 기본 동작은 다음 방법 중 하나로 바꿀 수 있어요.
- 인덱스를 만들 때
index.write.wait_for_active_shards인덱스 설정을 지정해요. 이 설정은 이후 쓰기 작업의wait_for_active_shards동작에도 영향을 줘요. - create index 요청에서
wait_for_active_shards쿼리 파라미터를 사용해요.
예제: index.write.wait_for_active_shards 설정 사용 (Example: Using the index.write.wait_for_active_shards setting)
다음 예제 요청은 반환하기 전에 두 개의 샤드 복사본이 활성화되기를 기다리는 index.write.wait_for_active_shards 설정으로 인덱스를 만들어요. 이 설정은 인덱스의 이후 쓰기 작업에도 영향을 줘요.
예제: wait_for_active_shards 쿼리 파라미터 사용 (Example: Using the wait_for_active_shards query parameter)
다음 예제 요청은 인덱스를 만들고, 반환하기 전에 두 개의 샤드 복사본(프라이머리와 복제본 1개)이 활성화되기를 기다리도록 wait_for_active_shards 쿼리 파라미터를 사용해요.
필요한 권한 (Required permissions)
Security plugin을 사용한다면 indices:admin/create 권한이 있는지 확인하세요.