Search API

search API 작업은 클러스터에서 데이터를 검색할 수 있게 해줘요.

도입 버전 1.0

엔드포인트

GET /{index}/_search
GET /_search

POST /{index}/_search
POST /_search

쿼리 파라미터

모든 파라미터는 선택 사항이에요.

많은 파라미터는 URL q= 파라미터나 query_string 쿼리를 사용할 때만 적용돼요. 자세한 내용은 Query string query를 참고하세요.

파라미터	유형	설명
allow_no_indices	Boolean	어떤 인덱스와도 일치하지 않는 와일드카드를 무시할지 여부예요. 기본값은 true 예요. 예: `GET test-index-*/_search?allow_no_indices=true`.
allow_partial_search_results	Boolean	요청에서 오류가 발생하거나 타임아웃되면 부분 결과를 반환할지 여부예요. 기본값은 true 예요. 예: `GET test-index/_search?allow_partial_search_results=false`.
analyzer	String	쿼리 문자열에서 사용할 분석기(analyzer)예요. `q=` 또는 query_string 본문이 필요해요. 예: `GET test-index/_search?q=title:test&analyzer=standard`.
analyze_wildcard	Boolean	update 작업이 분석에 와일드카드 및 접두어 쿼리를 포함할지 여부예요. 기본값은 false 예요. `q=` 또는 query_string 이 필요해요. 예: `GET test-index/_search?q=title:te*&analyze_wildcard=true`.
batched_reduce_size	Integer	최종 검색 결과를 반환하기 전에 코디네이팅 노드에서 한 배치로 결합할 샤드 결과 수예요. 함께 처리되는 샤드 결과 수를 제한해, 검색 요청이 많은 샤드에 걸쳐 있을 때 메모리 사용을 줄이는 데 도움이 돼요. 기본값은 512 예요. 예: `GET test-index/_search?batched_reduce_size=2`.
cancel_after_time_interval	Time	이 시간이 지나면 검색 요청이 취소될 시간이에요. 요청 수준 파라미터가 cancel_after_time_interval 클러스터 설정 보다 우선해요. 기본값은 -1 이에요. 예: `GET test-index/_search?cancel_after_time_interval=10ms`.
ccs_minimize_roundtrips	Boolean	노드와 원격 클러스터 사이의 왕복 횟수를 최소화할지 여부예요. 기본값은 true 예요. 예: `GET test-index/_search?ccs_minimize_roundtrips=true`.
default_operator	String	문자열 쿼리의 기본 연산자예요. 유효한 값은 AND 와 OR 예요. 기본값은 OR 예요. `q=` 또는 query_string 이 필요해요. 예: `GET test-index/_search?q=title:test one&default_operator=AND`.
df	String	쿼리 문자열에 필드 접두어가 제공되지 않을 때 사용되는 기본 필드예요. `q=` 또는 query_string 이 필요해요. 예: `GET test-index/_search?q=test&df=title`.
docvalue_fields	String	doc values 표현에서 값을 반환할 필드의 쉼표로 구분된 목록이에요. Doc values는 집계, 정렬, 스크립팅의 성능을 개선하는 최적화된 컬럼형 형식이에요. 예: `GET test-index/_search?docvalue_fields=ts,views`.
expand_wildcards	String	와일드카드 표현식이 일치할 수 있는 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. 유효한 값은: - all : 숨겨진 것을 포함한 모든 인덱스와 일치. - closed : 닫혀 있고 숨겨지지 않은 인덱스와 일치. - hidden : 숨겨진 인덱스와 일치. open , closed 또는 둘 다와 결합해야 해요. - none : 와일드카드 표현식을 허용하지 않아요. - open : 열려 있고 숨겨지지 않은 인덱스와 일치. 기본값은 open 이에요. 예: `GET test-index-*/_search?expand_wildcards=open`.
explain	Boolean	true 면 OpenSearch가 각 문서의 관련성 점수를 어떻게 계산했는지에 대한 세부 정보를 반환해요. 기본값은 false 예요. 응답에 hits가 포함된 경우에만 적용돼요. 예: `GET test-index/_search?explain=true&size=1&q=title:test`.
from	Integer	검색을 시작할 시작 인덱스예요. 기본값은 0 이에요. 예: `GET test-index/_search?from=5&size=5`.
ignore_throttled	Boolean	구체적인 인덱스, 확장된 인덱스, 별칭이 있는 인덱스가 고정(frozen)된 경우 이를 무시할지 여부예요. 기본값은 true 예요. 예: `GET test-index/_search?ignore_throttled=true`.
ignore_unavailable	Boolean	true 면 OpenSearch는 검색 중에 없거나 닫힌 인덱스와 사용할 수 없는 샤드를 무시해요. false 면 요청이 없거나 닫힌 인덱스를 대상으로 할 때 오류를 반환해요. 기본값은 false 예요. 예: `GET test-index-*/_search?ignore_unavailable=true`.
include_named_queries_score	Boolean	각 히트에 대해 명명된 쿼리( _name 이 있는 쿼리)의 점수 기여를 반환할지 여부예요. 기본값은 false 예요. _name 으로 명명된 쿼리가 필요해요. 예: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}`.
lenient	Boolean	쿼리에 형식 오류가 있을 때(예: 숫자 필드를 텍스트로 쿼리) 오류를 반환하는 대신 요청을 수락할지 여부예요. 기본값은 false 예요. `q=` 또는 query_string 이 필요해요. 예: `GET test-index/_search?q=views:abc&lenient=true`.
max_concurrent_shard_requests	Integer	이 요청이 각 노드에서 실행해야 하는 최대 동시 샤드 요청 수예요. 기본값은 5 예요. 예: `GET test-index/_search?max_concurrent_shard_requests=2`.
node_level_query_fanout	Boolean	제공 시 search.node_level_query_fanout.enabled 클러스터 설정을 덮어써 이 검색 요청에 노드 수준 쿼리 팬아웃(node-level query fan-out)을 사용할지 여부예요. 노드 수준 쿼리 팬아웃은 샤드 수준 query_then_fetch 쿼리와 can_match 요청을 대상 데이터 노드별로 그룹화해요. 기본값은 false 예요. 예: `POST index1/_search?node_level_query_fanout=true`.
phase_took	Boolean	응답에 단계 수준의 took 시간 값을 반환할지 여부예요. 기본값은 false 예요. 예: `GET test-index/_search?phase_took=true`.
pre_filter_shard_size	Integer	검색 샤드에 대한 사전 필터(prefilter) 작업을 트리거하기 위한 사전 필터 크기 임계값이에요. 검색 요청이 확장되는 샤드 수가 이 값을 초과하면 OpenSearch는 쿼리 다시 작성에 기반해 문서와 일치할 수 없는 샤드를 제거하는 사전 필터 작업을 수행해요. 기본값은 128 이에요. 예: `GET test-index/_search?pre_filter_shard_size=1`.
preference	String	OpenSearch가 검색을 수행해야 하는 샤드나 노드를 지정해요. 유효한 값은 preference 쿼리 파라미터 를 참고하세요. 예: `GET test-index/_search?preference=_local`.
q	String	Lucene 쿼리 문자열 쿼리예요. 쿼리 문자열 도우미를 활성화해요. 요청 본문의 query 파라미터보다 우선해요. 둘 다 지정되면 이 파라미터와 일치하는 문서만 반환되고 요청 본문의 쿼리는 무시돼요. 예: `GET test-index/_search?q=title:test&size=5`.
request_cache	Boolean	size=0 이 지정된 경우 요청에 대해 OpenSearch가 검색 결과 캐싱을 사용할지 여부예요. 기본값은 인덱스 수준의 request_cache 설정이에요. 예: `GET test-index/_search?request_cache=true`.
rest_total_hits_as_int	Boolean	hits.total 을 정수로 반환할지 여부예요. 그 외에는 객체를 반환해요. 기본값은 false 예요. track_total_hits 를 true 로 설정한 채 사용해요. 예: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true`.
routing	String	update by query 작업을 특정 샤드로 라우팅하는 데 사용되는 값이에요. 예: `GET test-index/_search?routing=user-42`.
scroll	Time	검색 컨텍스트를 열어 둘 시간이에요. size 가 0보다 크고 후속 _search/scroll 이 필요해요. 예: `GET test-index/_search?scroll=1m&size=2`.
search_type	String	관련성 점수를 계산할 때 OpenSearch가 전역 용어·문서 빈도를 사용할지 여부예요. 유효한 값은 query_then_fetch 와 dfs_query_then_fetch 예요. query_then_fetch 는 샤드의 로컬 용어·문서 빈도를 사용해 문서에 점수를 매겨요. 보통 더 빠르지만 덜 정확해요. dfs_query_then_fetch 는 모든 샤드의 전역 용어·문서 빈도를 사용해 문서에 점수를 매겨요. 보통 더 느리지만 더 정확해요. 기본값은 query_then_fetch 예요. 예: `GET test-index/_search?search_type=dfs_query_then_fetch`.
seq_no_primary_term	Boolean	각 문서 히트의 마지막 작업의 시퀀스 번호와 주 용어(primary term)를 반환할지 여부예요. 예: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test`.
size	Integer	응답에 포함할 결과 수예요. 예: `GET test-index/_search?size=3`.
sort	List	정렬할 `<field>:<direction>` 쌍의 쉼표로 구분된 목록이에요. 점수 필드가 아닌 필드로 정렬하면서 점수를 원한다면 track_scores=true 를 사용하세요. 예: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`.
_source	String 또는 Boolean	응답에 제공되는 _source 필드를 제어해요. 유효한 값은 true (문서 소스 반환), false (문서 소스 반환 안 함), (소스에서 반환할 필드, 목록이나 와일드카드 패턴으로 제공)이에요. 자세한 내용은 Source filtering 을 참고하세요. 예: `GET test-index/_search?_source=false&size=1`, `GET test-index/_search?_source=titl*&size=1`, `GET test-index/_search?_source=title,description&size=1`.
_source_excludes	List	응답에서 제외할 소스 필드의 쉼표로 구분된 목록이에요. _source 파라미터가 false 면 이 파라미터는 무시돼요. 자세한 내용은 Source filtering 을 참고하세요. 예: `GET test-index/_search?_source_excludes=title&size=1`.
_source_includes	List	응답에 포함할 소스 필드의 쉼표로 구분된 목록이에요. _source 파라미터가 false 면 이 파라미터는 무시돼요. 자세한 내용은 Source filtering 을 참고하세요. 예: `GET test-index/_search?_source_includes=title&size=1`.
stats	String	요청과 연결할 검색 통계 그룹의 쉼표로 구분된 목록이에요. 예: `GET test-index/_search?stats=group1`.
stored_fields	List	GET 작업이 인덱스에 저장된 필드를 검색할지 여부예요. 기본값은 false 예요. 예: `GET test-index-stored/_search?stored_fields=note&size=1`.
terminate_after	Integer	요청을 종료하기 전에 OpenSearch가 처리해야 하는 최대 일치 문서(hit) 수예요. 기본값은 0 (최대치 없음)이에요. 예: `GET test-index/_search?terminate_after=1&size=10`.
timeout	Time	활성 샤드로부터 응답을 기다려야 하는 시간이에요. 기본값은 1m (1분)이에요. 예: `GET test-index/_search?timeout=10ms`.
track_scores	Boolean	문서 점수를 반환할지 여부예요. 기본값은 false 예요. sort 와 함께 사용해요. 예: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`.
track_total_hits	Boolean 또는 Integer	일치 문서를 얼마나 세어야 할지예요. 기본값은 10000 이에요. 자세한 내용은 Track total hits 를 참고하세요. 예: `GET test-index/_search?track_total_hits=2`.
typed_keys	Boolean	반환된 집계와 제안된 용어가 응답에 유형을 포함할지 여부예요. 기본값은 true 예요. 집계나 suggester에만 적용돼요. 예: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}`.
version	Boolean	문서 버전을 일치 항목으로 포함할지 여부예요. 예: `GET test-index/_search?version=true&size=1&q=title:test`.

`preference` 쿼리 파라미터

preference 쿼리 파라미터는 OpenSearch가 검색을 수행해야 하는 샤드나 노드를 지정해요. 유효한 값은 다음과 같아요:

_primary: 주 샤드에서만 검색을 수행해요.
_replica: 복제 샤드에서만 검색을 수행해요.
_primary_first: 주 샤드에서 검색을 수행하되, 주 샤드를 사용할 수 없으면 다른 사용 가능한 샤드로 장애 조치해요.
_replica_first: 복제 샤드에서 검색을 수행하되, 복제 샤드를 사용할 수 없으면 다른 사용 가능한 샤드로 장애 조치해요.
_local: 가능하면 로컬 노드의 샤드에서 검색을 수행해요.
_prefer_nodes:<node-id-1>,<node-id-2>: 가능하면 지정된 노드에서 검색을 수행해요. 여러 노드를 지정하려면 쉼표로 구분된 목록을 사용하세요.
_shards:<shard-id-1>,<shard-id-2>: 지정된 샤드에서만 검색을 수행해요. 여러 샤드를 지정하려면 쉼표로 구분된 목록을 사용하세요. 다른 선호도와 결합할 때 _shards 선호도가 먼저 나열되어야 해요. 예: _shards:1,2|_replica.
_only_nodes:<node-id-1>,<node-id-2>: 지정된 노드에서만 검색을 수행해요. 여러 노드를 지정하려면 쉼표로 구분된 목록을 사용하세요.
<string>: 검색에 사용할 사용자 지정 문자열을 지정해요. 문자열은 밑줄 문자(_)로 시작할 수 없어요. 같은 사용자 지정 문자열을 가진 검색은 같은 샤드로 라우팅돼요.

요청 본문

모든 필드는 선택 사항이에요.

필드	유형	설명
aggs	Object	선택 사항인 aggs 파라미터에서 원하는 수의 집계를 정의할 수 있어요. 각 집계는 이름과 OpenSearch가 지원하는 집계 유형 중 하나로 정의돼요. 자세한 내용은 Aggregations 를 참고하세요.
docvalue_fields	객체 배열	doc_values 형식으로 반환할 필드예요. 반환 값에 형식을 포함할 수 있어요(예: 날짜 형식). knn_vector 필드의 경우 지원되는 형식은 binary (기본값, Base64 인코딩)와 array (JSON 숫자 배열)예요. 자세한 내용은 Retrieving vector fields using docvalue_fields 를 참고하세요.
fields	Array	요청에서 검색할 필드예요. 날짜·시간 같은 특정 형식으로 결과를 반환하려면 형식을 지정하세요.
explain	String	OpenSearch가 문서의 점수를 어떻게 계산했는지에 대한 세부 정보를 반환할지 여부예요. 기본값은 false 예요.
from	Integer	검색을 시작할 시작 인덱스예요. 기본값은 0이에요.
include_named_queries_score	Boolean	명명된 쿼리의 점수를 반환할지 여부예요.
indices_boost	객체 배열	특정 인덱스의 문서 _score 를 높여요. 각 항목은 `<index>:<boost-multiplier>` 형식으로 인덱스와 부스트 계수를 지정해요. 1.0보다 큰 부스트는 점수를 높이고, 0~1.0 사이의 부스트는 점수를 낮춰요.
min_score	Integer	임계값을 지정해 이 임계값 위의 문서만 반환해요.
query	Object	요청에서 사용할 DSL 쿼리예요.
seq_no_primary_term	Boolean	각 문서 히트의 마지막 작업의 시퀀스 번호와 주 용어를 반환할지 여부예요.
size	Integer	반환할 결과 수예요. 기본값은 10이에요.
sort	객체 또는 문자열 배열	결과를 정렬하는 방법을 지정해요. 필드 이름, 필드 및 정렬 옵션이 있는 객체, 또는 이들의 배열일 수 있어요. Sorting results 를 참고하세요.
_source	Boolean, String, 문자열 배열 또는 Object	각 히트에서 반환할 문서 소스 필드예요. 기본값은 true (전체 문서 반환)예요. 자세한 내용은 Source filtering 을 참고하세요.
stats	문자열 배열	요청과 연결할 검색 통계 그룹 목록이에요.
suggest_field	String	제안에 사용할 필드예요. suggest_text 와 함께, 선택적으로 suggest_mode 또는 suggest_size 와 함께 사용해요.
suggest_mode	String	검색할 때 사용할 모드예요. 유효한 값은 always ( suggest_text 의 용어에 기반해 제안 제공), popular (검색 용어보다 샤드에서 더 많은 문서에 나타나는 제안 제공), missing (샤드에 없는 용어에 대한 제안 제공)이에요. suggest_field 와 suggest_text 가 필요해요.
suggest_size	Integer	반환할 제안 수예요. suggest_field 와 suggest_text 가 필요해요.
suggest_text	String	OpenSearch가 제안을 반환해야 하는 입력 텍스트예요. suggest_field 와 suggest_text 가 필요해요.
terminate_after	Integer	요청을 종료하기 전에 OpenSearch가 처리해야 하는 최대 일치 문서(hit) 수예요. 기본값은 0이에요.
timeout	Time	응답을 기다릴 시간이에요. 기본값은 타임아웃 없음이에요.
version	Boolean	응답에 문서 버전을 포함할지 여부예요.

검색 통계 그룹 (Search stats groups)

요청 본문의 stats 필드나 쿼리 파라미터로 그룹 이름을 지정해 검색 요청을 하나 이상의 통계 그룹과 연결할 수 있어요. OpenSearch는 Index Stats API로 검색할 수 있는 그룹별 검색 통계를 유지해요.

다음 예제는 검색 요청을 두 그룹과 연결해요:

POST /my-index/_search
{
  "query": {
    "match_all": {}
  },
  "stats": ["group1", "group2"]
}

특정 그룹의 검색 통계를 검색하려면 Index Stats API의 groups 쿼리 파라미터를 사용하세요:

GET /my-index/_stats/search?groups=group1,group2

모든 그룹의 통계를 반환하려면 _all을 사용하세요:

GET /my-index/_stats/search?groups=_all

예제 요청

GET /movies/_search
{
  "query": {
    "match": {
      "director": "Christopher Nolan"
    }
  }
}

예제 응답

다음 예제 응답은 검색 응답의 구조를 보여줘요:

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.42727602,
    "hits": [
      {
        "_index": "movies",
        "_id": "1",
        "_score": 0.42727602,
        "_source": {
          "title": "The Dark Knight",
          "director": "Christopher Nolan",
          "year": 2008,
          "genre": "Action"
        }
      },
      {
        "_index": "movies",
        "_id": "2",
        "_score": 0.42727602,
        "_source": {
          "title": "Inception",
          "director": "Christopher Nolan",
          "year": 2010,
          "genre": "Science Fiction"
        }
      }
    ]
  }
}

응답 본문 필드

다음 표는 최상위 응답 본문 필드를 보여줘요.

필드	데이터 타입	설명
took	Integer	OpenSearch가 검색을 실행하는 데 걸린 시간(밀리초)이에요. 코디네이팅 노드가 요청을 받은 순간부터 응답을 보낼 준비가 될 때까지 측정되므로, 코디네이팅 노드와 데이터 노드 간의 통신, 검색 스레드 풀에서 대기한 시간, 검색 자체를 포함해요. 네트워크를 통한 요청 또는 응답 전송에 걸린 시간은 포함하지 않아요.
phase_took	Object	각 검색 단계( can_match , dfs_pre_query , query , dfs_query , fetch , expand )에 소요된 시간(밀리초)이에요. phase_took 쿼리 파라미터가 true 인 경우에만 반환돼요.
timed_out	Boolean	완료되기 전에 검색이 타임아웃되었는지 여부예요. true 면 반환된 결과가 부분적이거나 비어 있을 수 있어요.
terminated_early	Boolean	OpenSearch가 terminate_after 에 지정된 문서 수를 수집해 검색을 일찍 중지했는지 여부예요. terminate_after 가 설정된 경우에만 반환돼요.
_shards	Object	검색이 실행된 샤드 수와 각 샤드 그룹의 결과예요.
hits	Object	일치하는 문서와 그 메타데이터예요.
aggregations	Object	집계 이름으로 키가 지정된 집계 결과예요. 요청 본문에 aggs 객체가 있는 경우에만 반환돼요.
suggest	Object	제안기 이름으로 키가 지정된 제안 결과예요. 요청 본문에 suggest 객체가 있는 경우에만 반환돼요.
profile	Object	쿼리 및 fetch 단계에 대한 샤드별 타이밍 세부 정보예요. 요청 본문이 profile 을 true 로 설정한 경우에만 반환돼요. 자세한 내용은 Profile API 를 참고하세요.
_scroll_id	String	검색 컨텍스트를 식별하는 스크롤 ID예요. 이 값을 Scroll API에 전달해 다음 결과 배치를 검색해요. 요청에 scroll 쿼리 파라미터가 포함된 경우에만 반환돼요.
pit_id	String	검색 컨텍스트를 식별하는 Point in Time(PIT) ID예요. 요청이 PIT를 검색하는 경우에만 반환돼요. 자세한 내용은 Point in Time API 를 참고하세요.
_clusters	Object	크로스 클러스터 검색이 실행된 클러스터 수와 각 클러스터 그룹의 결과예요. 크로스 클러스터 검색에서만 반환돼요.
num_reduce_phases	Integer	OpenSearch가 부분 샤드 결과를 최종 결과 집합으로 결합하기 위해 수행한 reduce 단계 수예요. 검색이 둘 이상의 reduce 단계를 사용할 때만 반환돼요.

다음 표는 _shards 객체의 필드를 보여줘요.

필드	데이터 타입	설명
total	Integer	검색이 쿼리해야 했던 샤드 수로, 할당되지 않은 샤드를 포함해요.
successful	Integer	검색을 성공적으로 실행한 샤드 수예요.
skipped	Integer	예비 검사에서 샤드의 어떤 문서도 일치할 수 없다고 판단해 검색을 건너뛴 샤드 수예요. 검색에 범위 필터가 포함되어 있고 샤드의 모든 값이 그 범위 밖에 있는 경우에 흔히 발생해요.
failed	Integer	검색 실행에 실패한 샤드 수예요. 할당되지 않은 샤드는 성공도 실패도 아닌 것으로 간주되므로, successful 와 failed 가 total 보다 작게 합산되면 일부 샤드가 할당되지 않은 것이에요.

다음 표는 hits 객체의 필드를 보여줘요.

필드	데이터 타입	설명
total	Object	일치하는 문서 수예요. 개수를 담은 value 필드와, 개수가 정확하면 eq 이고 개수가 하한이면 gte 인 relation 필드를 포함해요. track_total_hits 가 false 면 생략돼요.
max_score	Float	일치하는 문서 중 가장 높은 _score 예요. 검색이 _score 로 정렬하지 않으면 null 이에요.
hits	객체 배열	관련성 또는 지정된 정렬 순서로 정렬된 일치 문서예요.

다음 표는 hits.hits 배열의 각 객체에 있는 필드를 보여줘요.

필드	데이터 타입	설명
_index	String	문서를 포함하는 인덱스의 이름이에요.
_id	String	문서 ID예요. 이 ID는 반환된 인덱스 안에서만 고유해요.
_score	Float	문서의 관련성 점수예요. 검색이 _score 로 정렬하지 않으면 null 이에요.
_source	Object	인덱싱 시점에 제공된 원본 JSON 문서예요. 이 필드를 생략하거나 특정 필드만 반환하려면 Source filtering 을 참고하세요.
fields	Object	docvalue_fields 또는 stored_fields 로 검색된 필드 값이에요. 요청이 두 파라미터 중 하나를 지정한 경우에만 반환돼요.
sort	Array	문서의 정렬 값이에요. 요청 본문에 sort 배열이 있는 경우에만 반환돼요. 마지막 히트의 값을 search_after 로 전달해 다음 결과 페이지를 검색해요.
highlight	Object	필드 이름으로 키가 지정된 강조 표시된 스니펫이에요. 요청 본문에 highlight 객체가 있는 경우에만 반환돼요.
matched_queries	문자열 배열	문서가 일치한 명명된 쿼리의 이름이에요. 검색이 _name 파라미터를 사용하는 경우에만 반환돼요.
inner_hits	Object	일치하는 중첩, 자식 또는 부모 문서예요. 요청 본문에 inner_hits 객체가 있는 경우에만 반환돼요.
_explanation	Object	OpenSearch가 문서의 관련성 점수를 어떻게 계산했는지에 대한 분석이에요. explain 이 true 인 경우에만 반환돼요.
_shard	String	문서를 반환한 샤드예요. explain 이 true 인 경우에만 반환돼요.
_node	String	문서를 반환한 노드예요. explain 이 true 인 경우에만 반환돼요.

Source filtering

응답의 각 히트에는 원본 JSON 문서를 담은 _source 객체가 있어요. 모든 히트에 대해 전체 문서를 반환하면 대부분의 애플리케이션이 필요로 하는 것보다 더 많은 데이터를 전송하게 돼요. Source filtering은 OpenSearch가 _source에서 반환하는 필드를 제한해요.

다음 표는 _source 요청 본문 파라미터의 허용 값을 보여줘요.

값	설명
true	전체 문서를 반환해요. 기본값이에요.
false	각 히트에서 _source 객체를 생략해요.
String	details.* 같은 필드 이름 또는 와일드카드 패턴이에요. OpenSearch는 일치하는 필드만 반환해요.
문자열 배열	["name", "details.*"] 같은 필드 이름 또는 와일드카드 패턴 목록이에요.
Object	includes 와 excludes 목록을 담은 객체예요. excludes 가 우선하므로 두 목록 모두의 패턴과 일치하는 필드는 반환되지 않아요.

요청 본문 대신 요청 URL에서 소스를 필터링하려면 _source, _source_includes, _source_excludes 쿼리 파라미터를 사용하세요.

예시와 제한 사항은 Using source filtering을 참고하세요.

Track total hits

일치하는 문서를 정확하게 세려면 모든 일치 항목을 방문해야 하므로, 많은 문서와 일치하는 쿼리에는 비용이 들어요. track_total_hits 파라미터는 OpenSearch가 세는 일치 항목 수를 제한해요. 쿼리 파라미터로 지정하거나 요청 본문에 지정할 수 있어요.

기본적으로 OpenSearch는 10000까지 일치 항목을 정확하게 세요. 더 많은 문서가 일치하면 hits.total.value는 10000을 보고하고 hits.total.relation은 gte가 되어, 쿼리가 그 이상의 문서와 일치했음을 나타내요.

다음 표는 track_total_hits의 허용 값을 보여줘요.

값	설명
true	모든 일치 문서를 세요. hits.total.relation 은 항상 eq 예요.
false	히트 계산을 비활성화해요. 응답에 hits.total 객체가 없어요.
Integer	지정된 수까지 일치 문서를 정확하게 세요. 더 많은 문서가 일치하면 hits.total.value 는 임계값을 보고하고 hits.total.relation 은 gte 예요.

모든 일치 항목을 세면 많은 문서와 일치하는 검색이 느려져요. 애플리케이션이 정확한 개수를 요구할 때만 임계값을 높이세요.

예제: 기본 히트 계산

다음 예제는 track_total_hits를 지정하지 않고 10,500개의 문서가 있는 logs 인덱스를 검색해요:

GET /logs/_search
{
  "size": 0,
  "query": {
    "match_all": {}
  }
}

relation이 gte이므로 인덱스에는 최소 10,000개의 일치 문서가 있어요:

{
  "hits": {
    "total": {
      "value": 10000,
      "relation": "gte"
    },
    "max_score": null,
    "hits": []
  }
}

예제: 모든 일치 문서 계산

모든 일치 항목을 세려면 track_total_hits를 true로 설정하세요:

GET /logs/_search
{
  "size": 0,
  "track_total_hits": true,
  "query": {
    "match_all": {}
  }
}

relation이 eq이므로 value는 일치하는 문서의 정확한 수예요:

{
  "hits": {
    "total": {
      "value": 10500,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  }
}

`ext` 객체

도입 버전 2.10

플러그인 작성자는 검색 요청과 검색 응답 모두에 ext 객체를 추가할 수 있어요. ext 객체는 플러그인별 필드를 담고 있어, 플러그인이 요청에 추가 파라미터를 전달하거나 응답에 추가 정보를 반환할 수 있게 해요.

검색 응답에서 `ext` 사용

플러그인은 검색 응답에 ext 객체를 추가해 플러그인별 응답 필드를 포함할 수 있어요. 예를 들어 대화형 검색에서 검색 증강 생성(RAG)의 결과는 단일 "히트"(답변)예요. 플러그인 작성자는 이 답변을 검색 히트와 분리되도록 ext 객체의 일부로 검색 응답에 포함할 수 있어요. 다음 예제 응답에서 RAG 결과는 ext.retrieval_augmented_generation.answer 필드에 있어요:

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 3,
    "successful": 3,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 110,
      "relation": "eq"
    },
    "max_score": 0.55129033,
    "hits": [
      {
       "_index": "...",
        "_id": "...",
        "_score": 0.55129033,
        "_source": {
          "text": "...",
          "title": "..."
        }
      },
      {
      ...
      }
      ...
      {
      ...
      }
    ],
  }, // end of hits
  "ext": {
    "retrieval_augmented_generation": { // a search response processor
      "answer": "RAG answer"
    }
  }
}

검색 요청에서 `ext` 사용

플러그인은 검색 요청에 ext 객체를 받아 플러그인별 파라미터를 제공할 수도 있어요. 요청의 ext 객체 구조와 내용은 플러그인 구현에 따라 달라져요. 요청 ext 객체에서 지원되는 특정 필드는 플러그인 문서를 참고하세요.

다음 예제는 ext 객체를 포함한 검색 요청을 보여줘요. ext 안의 정확한 필드는 어떤 플러그인이 설치되어 있고 어떤 파라미터를 받는지에 따라 달라져요:

POST /my-index/_search
{
  "query": {
    "match": {
      "field": "value"
    }
  },
  "ext": {
    "my_plugin": {
      "custom_parameter": "value"
    }
  }
}

필요한 권한

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

출처: 문서

Search API

Search API

엔드포인트

쿼리 파라미터

preference 쿼리 파라미터

요청 본문

검색 통계 그룹 (Search stats groups)

예제 요청

예제 응답

응답 본문 필드

Source filtering

Track total hits

예제: 기본 히트 계산

예제: 모든 일치 문서 계산

ext 객체

검색 응답에서 ext 사용

검색 요청에서 ext 사용

필요한 권한

`preference` 쿼리 파라미터

`ext` 객체

검색 응답에서 `ext` 사용

검색 요청에서 `ext` 사용