인덱스 설정 조회 API

인덱스 설정 조회 API (Get Index Settings API)

1.0부터 도입되었어요.

인덱스 설정 조회(Get Index Settings) API는 하나 이상의 인덱스에 대한 구성 설정을 반환해요. 샤드 수와 복제본 수, 리프레시 간격, 분석 구성 등 인덱스 수준 설정을 가져올 때 이 API를 사용해요.

출처: 문서

본문

엔드포인트

GET /_settings
GET /{target-index}/_settings
GET /{target-index}/_settings/{setting}

경로 파라미터

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

파라미터	데이터 타입	설명
`target-index`	String	설정을 가져올 인덱스의 이름이에요. 단일 인덱스 이름, 쉼표로 구분된 인덱스 이름 목록, 또는 와일드카드 표현식을 지정할 수 있어요. 클러스터의 모든 인덱스 설정을 가져오려면 `_all` 또는 `*`을 사용해요.
`setting`	String	가져올 특정 설정의 이름이에요. 지정하면 모든 설정 대신 요청한 설정만 응답에 포함돼요.

쿼리 파라미터

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

파라미터	데이터 타입	설명
`allow_no_indices`	Boolean	어떤 인덱스와도 일치하지 않는 와일드카드 표현식이나 인덱스 패턴을 무시할지 지정해요. `false`이면 와일드카드 표현식이 어떤 인덱스와도 일치하지 않을 때 오류를 반환해요. `true`이면 누락된 인덱스를 무시하고 존재하는 인덱스의 설정만 반환해요. 기본값은 `true`예요.
`expand_wildcards`	String	와일드카드 표현식이 확장될 수 있는 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. 유효한 값은 `all`(모든 인덱스), `open`(열린 인덱스), `closed`(닫힌 인덱스), `hidden`(숨은 인덱스), `none`(와일드카드 표현식을 받지 않음)이에요. 기본값은 `open`이에요.
`flat_settings`	Boolean	설정을 평평한 형식으로 반환할지 지정해요. `true`면 설정이 평평한 형태로 반환되고(예: `"index.creation_date": "123456789"`), `false`면 중첩된 형태로 반환돼요(예: `"index": {"creation_date": "123456789"}`). 기본값은 `false`예요.
`include_defaults`	Boolean	응답에 기본 설정을 포함할지 지정해요. 기본 설정은 명시적으로 설정하지 않았을 때 OpenSearch가 암묵적으로 적용하는 구성으로, OpenSearch 플러그인이 사용하는 설정도 포함해요. `true`면 사용자 설정과 기본 설정을 모두 포함하고, `false`면 사용자 설정만 포함해요. 기본값은 `false`예요.
`ignore_unavailable`	Boolean	누락되었거나 닫힌 인덱스를 무시할지 지정해요. `true`면 대상 인덱스가 누락되었거나 닫혀 있어도 오류를 반환하지 않아요. `false`면 대상 인덱스를 사용할 수 없을 때 오류를 반환해요. 기본값은 `false`예요.
`local`	Boolean	로컬 노드에서 설정을 가져올지 아니면 클러스터 매니저 노드에서 가져올지 지정해요. `true`면 로컬 노드에서, `false`면 클러스터 매니저 노드에서 가져와요. 기본값은 `false`예요.
`cluster_manager_timeout`	Time	클러스터 매니저 노드에 연결될 때까지 기다리는 시간이에요. 기본값은 `30s`예요.

요청 예시: 단일 인덱스의 설정 가져오기

다음 예제는 books 인덱스의 모든 설정을 가져와요:

GET /books/_settings

요청 예시: 여러 인덱스의 설정 가져오기

다음 예제는 여러 인덱스의 설정을 가져와요:

GET /books,products/_settings

요청 예시: 모든 인덱스의 설정 가져오기

다음 예제는 클러스터의 모든 인덱스 설정을 가져와요:

GET /_all/_settings

요청 예시: 와일드카드 패턴으로 설정 가져오기

다음 예제는 와일드카드 패턴을 사용해 패턴과 일치하는 모든 인덱스의 설정을 가져와요:

GET /logs-*/_settings

요청 예시: 이름으로 설정 필터링하기

다음 예제는 지정된 패턴과 일치하는 설정만 반환하도록 응답을 필터링해요:

GET /logs-*/_settings/index.number_*

응답 예시

기본적으로 설정은 중첩 형식으로 반환돼요:

{
  "books": {
    "settings": {
      "index": {
        "replication": {
          "type": "DOCUMENT"
        },
        "number_of_shards": "2",
        "provided_name": "books",
        "creation_date": "1778255937147",
        "number_of_replicas": "1",
        "uuid": "Onnd4TKBQMODrfvAvNXjAg",
        "version": {
          "created": "137277827"
        }
      }
    }
  }
}

응답 예시: 평평한 형식

flat_settings=true를 지정하면 설정이 평평한 형식으로 반환돼요:

{
  "books": {
    "settings": {
      "index.creation_date": "1778255937147",
      "index.number_of_replicas": "1",
      "index.number_of_shards": "2",
      "index.provided_name": "books",
      "index.replication.type": "DOCUMENT",
      "index.uuid": "Onnd4TKBQMODrfvAvNXjAg",
      "index.version.created": "137277827"
    }
  }
}

응답 본문 필드

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

필드	설명
`settings`	인덱스의 모든 설정을 담은 객체예요. 반환되는 구체적인 설정은 인덱스 구성에 따라 달라져요. 사용 가능한 인덱스 설정에 대한 자세한 내용은 Index settings를 참고해요.

필요한 권한

보안 플러그인을 사용한다면 다음 권한이 필요해요: indices:monitor/settings/get.

더 알아보기 (Learn more)

OpenSearch 공식 문서