인덱스 샤드 저장소 API

인덱스 샤드 저장소 API (Index Shard Stores API)

1.0부터 도입되었어요.

_shard_stores API는 하나 이상의 인덱스에 대한 샤드 복사본 정보를 제공해요. 이 API는 샤드가 왜 할당되지 않았는지와 현재 상태를 보여줌으로써, 할당되지 않은 샤드의 문제를 진단하는 데 도움을 줘요.

출처: 문서

본문

엔드포인트

GET /_shard_stores
GET /{index}/_shard_stores

경로 파라미터

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

파라미터	데이터 타입	설명
`index`	List or String	요청을 제한하는 데 사용하는 데이터 스트림, 인덱스, 별칭의 목록이에요.

쿼리 파라미터

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

파라미터	데이터 타입	설명	기본값
`allow_no_indices`	Boolean	`false`이면 어떤 와일드카드 표현식, 인덱스 별칭, 또는 `_all` 값이 누락되거나 닫힌 인덱스만 대상으로 하면 오류를 반환해요. 이 동작은 요청이 다른 열린 인덱스도 대상으로 하더라도 적용돼요.	`false`
`expand_wildcards`	List or String	와일드카드 패턴이 일치할 수 있는 인덱스 유형이에요. 요청이 데이터 스트림을 대상으로 할 수 있다면 이 인자는 와일드카드 표현식이 숨은 데이터 스트림과 일치하는지 결정해요. 유효한 값은 `all`(숨은 인덱스를 포함한 모든 인덱스 매치), `closed`(숨기지 않은 닫힌 인덱스 매치), `hidden`(숨은 인덱스 매치 — open, closed, 또는 둘 다와 함께 사용해야 해요), `none`(와일드카드 표현식을 받지 않음), `open`(숨기지 않은 열린 인덱스 매치)이에요.	`open`
`ignore_unavailable`	Boolean	`true`이면 누락되거나 닫힌 인덱스가 응답에 포함되지 않아요.	`false`
`status`	List or String	요청을 제한하는 데 사용하는 샤드 건강 상태의 목록이에요. 유효한 값은 `all`(건강 상태와 무관하게 모든 샤드 반환), `green`(프라이머리 샤드와 모든 복제본 샤드가 할당됨), `red`(프라이머리 샤드가 할당되지 않음), `yellow`(복제본 샤드 하나 이상이 할당되지 않음)이에요.	`yellow,red`

요청 예시

단일 노드 클러스터에 여러 프라이머리 샤드가 있는 인덱스를 만들어요:

PUT /logs-shardstore
{
  "settings": {
    "number_of_shards": 2,
    "number_of_replicas": 0
  },
  "mappings": {
    "properties": {
      "timestamp": { "type": "date" },
      "message": { "type": "text" }
    }
  }
}

문서 하나를 인덱싱해요:

POST /logs-shardstore/_doc
{
  "timestamp": "2025-06-20T12:00:00Z",
  "message": "Log message 1"
}

logs-shardstore 인덱스의 샤드 저장소 상태를 가져와요:

GET /logs-shardstore/_shard_stores?status=all

응답 예시

응답은 각 샤드에 할당된 저장소를 나열해요. 샤드에 할당된 저장소가 없으면 unassigned로 표시돼요:

{
  "indices": {
    "logs-shardstore": {
      "shards": {
        "0": {
          "stores": [
            {
              "UFyVYVMCSDOObiRwPxSW5w": {
                "name": "opensearch-node1",
                "ephemeral_id": "vkSB_-M7QVyFXvgda6oRZg",
                "transport_address": "172.19.0.2:9300",
                "attributes": {
                  "shard_indexing_pressure_enabled": "true"
                }
              },
              "allocation_id": "PEM5YjEWSz-jJEj-Not6Aw",
              "allocation": "primary"
            }
          ]
        },
        "1": {
          "stores": []
        }
      }
    }
  }
}

응답 본문 필드

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

필드	데이터 타입	설명
`indices`	Object	각 인덱스에 대한 샤드 저장소 정보를 담고 있어요.
`indices.<index>.shards`	Object	인덱스의 각 샤드에 대한 저장소 데이터를 담고 있어요.
`shards.<shard_id>.stores`	Array	샤드의 저장소 항목 목록이에요.
`stores[n].<node_id>`	Object	이름, 전송 주소, 속성을 포함한 노드 메타데이터예요.
`stores[n].allocation`	String	이 노드에서의 샤드 역할(`primary` 또는 `replica`)이에요.
`stores[n].allocation_id`	String	이 샤드 복사본의 고유 할당 ID예요.
`stores[n].store_exception`	Object (optional)	샤드 저장소를 읽을 때 발생한 예외를 저장해요.
`stores[n].store_exception.type`	String	예외의 유형이에요.
`stores[n].store_exception.reason`	String	예외의 이유 메시지예요.

필요한 권한

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

더 알아보기 (Learn more)

OpenSearch 공식 문서