검색 샤드 API

검색 샤드 API (Search shards API)

_search_shards API는 검색 요청을 실행한다면 OpenSearch가 어떤 샤드로 라우팅할지에 대한 정보를 제공해요. 검색을 실제로 실행하지 않고도 OpenSearch가 쿼리를 샤드들에 어떻게 분산할 계획인지 이해하는 데 도움이 되죠. 이 API는 검색을 실행하지 않으면서 라우팅 결정, 샤드 분포, 그리고 요청을 처리할 노드를 확인할 수 있게 해줘요.

도입 버전 1.0

엔드포인트

GET /_search_shards
GET /{index}/_search_shards
POST /_search_shards
POST /{index}/_search_shards

경로 파라미터

다음 표는 사용 가능한 경로 파라미터를 보여줘요. 모든 경로 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
String 쉼표로 구분된 대상 인덱스 이름 목록이에요.

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
allow_no_indices Boolean true 면 와일드카드 표현식이나 인덱스 별칭이 구체적인 인덱스로 해석되지 않아도 요청이 실패하지 않아요. 기본값은 true 예요.
expand_wildcards String 와일드카드 표현식의 확장 방식을 제어해요. 옵션은 open (기본값), closed , hidden , none , all 이에요.
ignore_unavailable Boolean true 면 없거나 닫힌 인덱스를 무시해요. 기본값은 false 예요.
local Boolean true 면 클러스터 매니저 노드에서 상태를 가져오지 않고 로컬 노드에서만 작업을 수행해요. 기본값은 false 예요.
preference String 대상으로 할 샤드나 노드를 선택할 때의 선호도를 지정해요. 자세한 내용은 preference 쿼리 파라미터를 참고하세요.
routing String 샤드 선택에 사용하는 특정 라우팅 값의 쉼표로 구분된 목록이에요.

요청 본문 필드

요청 본문에는 요청이 어떻게 라우팅될지 시뮬레이션하는 전체 검색 쿼리를 포함할 수 있어요:

{
  "query": {
    "term": {
      "user": "alice"
    }
  }
}

예제

인덱스를 생성해요:

PUT /logs-demo
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 0
  },
  "mappings": {
    "properties": {
      "user": { "type": "keyword" },
      "message": { "type": "text" },
      "@timestamp": { "type": "date" }
    }
  }
}

routing=user1로 첫 번째 문서를 인덱싱해요:

POST /logs-demo/_doc?routing=user1
{
  "@timestamp": "2025-05-23T10:00:00Z",
  "user": "user1",
  "message": "User login successful"
}

routing=user2로 두 번째 문서를 인덱싱해요:

POST /logs-demo/_doc?routing=user2
{
  "@timestamp": "2025-05-23T10:01:00Z",
  "user": "user2",
  "message": "User login failed"
}

예제 요청

_search_shards로 라우팅을 시뮬레이션해요:

POST /logs-demo/_search_shards?routing=user1
{
  "query": {
    "term": {
      "user": "user1"
    }
  }
}

예제 응답

응답은 검색을 실행했을 때 검색될 노드와 샤드를 보여줘요:

{
  "nodes": {
    "12ljrWLsQyiWHLzhFZgL9Q": {
      "name": "opensearch-node3",
      "ephemeral_id": "-JPvYKPMSGubd0VmSEzlbw",
      "transport_address": "172.18.0.4:9300",
      "attributes": {
        "shard_indexing_pressure_enabled": "true"
      }
    }
  },
  "indices": {
    "logs-demo": {}
  },
  "shards": [
    [
      {
        "state": "STARTED",
        "primary": true,
        "node": "12ljrWLsQyiWHLzhFZgL9Q",
        "relocating_node": null,
        "shard": 1,
        "index": "logs-demo",
        "allocation_id": {
          "id": "HwEjTdYQQJuULdQn10FRBw"
        }
      }
    ]
  ]
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
nodes Object 노드 ID를 이름, 전송 주소 같은 노드 메타데이터에 매핑하는 맵을 담고 있어요.
indices Object 요청에 포함된 인덱스 이름의 맵을 담고 있어요.
shards 배열의 배열 요청에 대한 샤드 복제본(주/복제)을 나타내는 중첩 배열이에요.
shards.index String 인덱스 이름이에요.
shards.shard Integer 샤드 번호예요.
shards.node String 이 샤드를 포함하는 노드의 노드 ID예요.
shards.primary Boolean 주 샤드인지 여부예요.
shards.state String 현재 샤드 상태예요.
shards.allocation_id.id String 이 샤드 할당의 고유 ID예요.

필요한 권한

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인하세요: indices:admin/shards/search_shards.

출처: 문서