Update Index Settings API

1.0에서 도입

Update Index Settings API는 인덱스 수준 설정을 실시간으로 바꿔요. 동적(dynamic) 인덱스 설정은 언제든 업데이트할 수 있지만, 정적(static) 설정은 인덱스를 만든 뒤에는 바꿀 수 없어요. 정적·동적 인덱스 설정에 대한 자세한 내용은 Index settings 문서를 참고해요.

내장 인덱스 설정 외에도 개별 플러그인의 설정을 업데이트할 수 있어요. 기본값을 포함한 사용 가능한 모든 설정의 전체 목록을 보려면 GET <target-index>/_settings?include_defaults=true를 실행해요.

출처: 문서

본문

엔드포인트 (Endpoints)

PUT /{index}/_settings

경로 매개변수 (Path parameters)

다음 표는 사용 가능한 경로 매개변수예요. 모든 경로 매개변수는 선택 사항이에요.

매개변수	데이터 타입	설명
`index`	String	업데이트할 인덱스의 이름이에요. 단일 인덱스 이름, 쉼표로 구분된 인덱스 이름 목록, 와일드카드 표현식을 지정할 수 있어요. 클러스터의 모든 인덱스 설정을 업데이트하려면 `_all` 또는 `*`를 사용해요.

쿼리 매개변수 (Query parameters)

다음 표는 사용 가능한 쿼리 매개변수예요. 모든 쿼리 매개변수는 선택 사항이에요.

매개변수	데이터 타입	설명
`allow_no_indices`	Boolean	어떤 인덱스와도 일치하지 않는 와일드카드 표현식이나 인덱스 패턴을 무시할지 지정해요. `false`면 와일드카드가 어떤 인덱스와도 일치하지 않을 때 오류를 반환하고, `true`면 존재하지 않는 인덱스를 무시하고 존재하는 인덱스의 설정만 업데이트해요. 기본값은 `true`예요.
`expand_wildcards`	String	와일드카드 표현식이 확장될 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. 유효한 값은 `all`(모든 인덱스), `open`(열린 인덱스), `closed`(닫힌 인덱스), `hidden`(숨은 인덱스), `none`(와일드카드 표현식 미허용)이에요. 기본값은 `open`이에요.
`flat_settings`	Boolean	설정을 평면(flat) 형식으로 반환할지 지정해요. `true`면 평면화된 형식으로, `false`면 중첩 형식으로 반환돼요. 기본값은 `false`예요.
`ignore_unavailable`	Boolean	존재하지 않거나 닫힌 인덱스를 무시할지 지정해요. `true`면 대상 인덱스가 없거나 닫혀 있어도 오류를 반환하지 않고, `false`면 대상 인덱스를 사용할 수 없을 때 오류를 반환해요. 기본값은 `false`예요.
`preserve_existing`	Boolean	기존 인덱스 설정을 보존할지 지정해요. `true`면 기존 설정은 그대로 두고 새 설정만 적용해요. `false`면 제공된 값으로 기존 설정을 업데이트해요. 기본값은 `false`예요.
`cluster_manager_timeout`	Time	클러스터 매니저 노드에 연결되기를 기다리는 시간이에요. 기본값은 `30s`예요.
`timeout`	Time	응답을 기다리는 시간이에요. 기본값은 `30s`예요.

요청 본문 (Request body)

요청 본문에는 업데이트할 인덱스 설정이 들어 있어요. 평면 또는 중첩 형식으로 지정할 수 있어요.

필드	데이터 타입	설명
`settings`	Object	업데이트할 인덱스 설정이 담긴 객체예요. 사용 가능한 인덱스 설정 목록은 Index settings를 참고해요.

예시 요청: 단일 인덱스 설정 업데이트

다음 예시는 books 인덱스의 설정을 업데이트해요:

PUT /books/_settings
{
"index": {
"number_of_replicas": 2
}
}

Python 클라이언트로는 이렇게 호출해요:

response = client.indices.put_settings(
index = "books",
body = {
"index": {
"number_of_replicas": 2
}
}
)

예시 요청: 설정을 기본값으로 되돌리기

설정을 기본값으로 되돌리려면 값을 null로 지정해요:

PUT /books/_settings
{
"index": {
"refresh_interval": null
}
}

예시 요청: 여러 인덱스 설정 업데이트

다음 예시는 여러 인덱스의 설정을 업데이트해요:

PUT /books,products/_settings
{
"index": {
"number_of_replicas": 0
}
}

예시 요청: 벌크 색인에 최적화하기

인덱스를 벌크 색인 작업에 최적화하려면 refresh_interval을 -1로 설정해서 새로고침 간격을 비활성화해요. 벌크 색인이 끝나면 양수 값으로 되돌려 다시 활성화해요:

PUT /books/_settings
{
"index": {
"refresh_interval": "-1"
}
}

벌크 색인을 마친 뒤 새로고침 간격을 복원해요:

PUT /books/_settings
{
"index": {
"refresh_interval": "1s"
}
}

예시 응답 (Example response)

{
"acknowledged": true
}

응답 본문 필드 (Response body fields)

다음 표는 모든 응답 본문 필드를 정리한 거예요.

필드	데이터 타입	설명
`acknowledged`	Boolean	업데이트 요청을 받았는지 여부를 나타내요. `true`는 요청을 받았다는 뜻이에요. 설정이 실제로 적용됐다는 보장은 아니에요.

필요한 권한 (Required permissions)

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: indices:admin/settings/update.

Update Index Settings API