다중 문서 조회 API

다중 문서 조회 API (Multi-get Documents API)

1.0에서 도입되었어요. Multi-get Documents API는 하나의 요청으로 하나 이상의 인덱스에서 여러 문서를 조회해요. 이 작업은 개별 GET 요청을 여러 번 실행하는 것보다 효율적이에요. 네트워크 오버헤드를 줄이고 클러스터에 대한 왕복(round-trip)을 한 번으로 합치기 때문이에요.

이 API는 ID로 특정 문서를 조회해야 하고 어떤 문서를 가져올지 알 때 사용해요. 흔한 시나리오로는 다음이 있어요.

  • 알려진 ID 목록을 기반으로 사용자 프로필, 제품 상세 정보, 또는 다른 엔티티 배치를 조회할 때
  • 주문 레코드와 관련 고객 정보를 함께 가져오는 것처럼, 서로 다른 인덱스의 관련 문서를 단일 작업으로 가져올 때
  • 각 문서에 대해 어떤 필드를 반환할지 제어하면서 여러 문서를 조회하는 효율적인 데이터 접근 패턴을 구현할 때

출처: 문서

본문

부분 응답 (Partial responses)

Multi-get Documents API는 빠른 응답을 우선시해요. 작업 중 하나 이상의 샤드가 실패하면 부분 결과를 반환해요. 샤드 실패로 특정 문서를 가져올 수 없거나 문서가 존재하지 않으면, 성공적으로 조회된 문서를 반환하면서 해당 문서에 대한 오류 세부 정보를 응답에 포함해요. 이렇게 하면 일시적인 실패나 없는 문서가 전체 작업을 막지 않아요.

엔드포인트 (Endpoints)

GET  /_mget
POST /_mget
GET  /{index}/_mget
POST /{index}/_mget

경로 파라미터 (Path parameters)

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

파라미터 데이터 타입 설명
index String ids가 지정될 때 문서를 조회할 인덱스 이름이에요. docs 배열의 문서가 인덱스를 지정하지 않을 때도 사용해요.

쿼리 파라미터 (Query parameters)

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

파라미터 데이터 타입 설명 기본값
_source Boolean 또는 List 또는 String _source 필드를 반환할지 말지 true 또는 false로 설정하거나, 반환할 필드 목록으로 설정해요. N/A
_source_excludes List 또는 String 응답에서 제외할 소스 필드의 쉼표 구분 목록이에요. _source_includes 쿼리 파라미터에 지정된 부분 집합에서 필드를 제외하는 데도 사용할 수 있어요. N/A
_source_includes List 또는 String 응답에 포함할 소스 필드의 쉼표 구분 목록이에요. 이 파라미터를 지정하면 이 소스 필드만 반환돼요. _source_excludes 쿼리 파라미터로 이 부분 집합에서 필드를 제외할 수 있어요. _source 파라미터가 false이면 이 파라미터는 무시돼요. N/A
preference String 작업을 수행할 노드나 샤드를 지정해요. 기본적으로 무작위예요. random
realtime Boolean true이면 요청이 near real time이 아닌 real time이에요. N/A
refresh Boolean 또는 String true이면 문서를 조회하기 전에 관련 샤드를 새로고침해요. 유효한 값은 다음과 같아요.
- false : 영향받는 샤드를 새로고침하지 않아요.
- true : 영향받는 샤드를 즉시 새로고침해요.
- wait_for : 응답하기 전에 변경 사항이 보일 때까지 기다려요.		 N/A
routing List 또는 String 작업을 특정 샤드로 라우팅하는 데 사용하는 사용자 지정 값이에요. N/A
stored_fields List 또는 String true이면 문서의 _source 대신 인덱스에 저장된 문서 필드를 가져와요. N/A

요청 본문 필드 (Request body fields)

요청 본문은 조회할 문서를 지정해요. 요청 경로에 인덱스를 지정하지 않았다면 요청 본문의 각 문서에 인덱스 이름을 포함해야 해요. 다음 표는 사용 가능한 요청 본문 필드를 보여줘요.

필드 데이터 타입 설명
docs Array of objects 조회할 문서예요. ids 필드가 지정되지 않으면 필수예요. 각 객체는 _index, _id, routing, _source, stored_fields 필드를 포함할 수 있어요.
docs._index String 문서를 담고 있는 인덱스의 이름이에요. 요청 경로에 인덱스가 지정되지 않았다면 필수예요.
docs._id String 문서 ID예요. 필수예요.
docs.routing String 작업을 특정 샤드로 라우팅하는 데 사용하는 라우팅 값이에요. 문서를 인덱싱할 때 사용자 지정 라우팅 값을 사용했다면 필수예요.
docs._source Boolean, Array, 또는 Object 반환할 소스 필드를 제어해요. false이면 _source 필드가 응답에서 제외돼요. 배열이면 포함할 필드를 지정해요. 객체이면 필드 포함과 제외를 제어하는 includes와 excludes 배열을 포함할 수 있어요. 기본값은 true예요.
docs._source.includes Array of strings 응답에 포함할 소스 필드예요. 예를 들어 ["title", "author"]는 title과 author 필드만 반환해요.
docs._source.excludes Array of strings 응답에서 제외할 소스 필드예요. 예를 들어 ["internal_notes"]는 internal_notes 필드를 제외해요.
docs.stored_fields Array of strings _source 필드 대신 조회할 저장된 필드예요. 인덱스 매핑에 명시적으로 저장된 필드만 조회할 수 있어요. 지정하면 명시적으로 요청하지 않는 한 _source 필드는 반환되지 않아요.
ids Array of strings 모든 문서가 같은 인덱스에 있을 때 문서 ID를 지정하는 간단한 방법이에요. 요청 경로에 인덱스가 지정된 경우에만 사용할 수 있어요. 제공되면 docs 필드는 필요하지 않아요.

예제: 여러 인덱스에서 문서 조회 (Example: Retrieving documents from multiple indexes)

다음 예제는 books 인덱스에서 문서 하나와 articles 인덱스에서 문서 하나를 조회해요.

예제: IDs 배열 사용 (Example: Using the IDs array)

같은 인덱스에서 여러 문서를 조회할 때 경로에 인덱스를 지정하고 ids 배열을 사용하면 요청을 간단히 할 수 있어요. 다음 예제는 books 인덱스에서 세 개의 문서를 조회해요.

예제: 소스 필드 필터링 (Example: Filtering source fields)

_source 파라미터로 각 문서에 대해 반환할 필드를 제어할 수 있어요. 다음 예제는 서로 다른 소스 필터링 옵션을 보여줘요. 첫 번째 문서의 소스를 완전히 제외하고, 두 번째 문서는 특정 필드를 반환하며, 세 번째 문서는 includes를 사용해 선택된 필드만 반환해요.

예제: 저장된 필드 조회 (Example: Retrieving stored fields)

인덱스 매핑에 저장된 필드(stored field)가 있다면 문서 소스 대신 저장된 필드를 가져올 수 있어요. 다음 예제는 두 사용자 문서의 서로 다른 저장된 필드를 조회해요.

예제: 라우팅 값 지정 (Example: Specifying routing values)

문서를 인덱싱할 때 사용자 지정 라우팅을 사용했다면, 그 문서를 조회할 때 라우팅 값을 제공해야 해요. 다음 예제는 라우팅 값을 사용해 두 주문 문서를 조회해요. 첫 번째 문서는 쿼리 파라미터의 라우팅 값을 사용하고, 두 번째 문서는 자신의 라우팅 값을 지정해요.

예제 응답 (Example response)

Multi-get Documents API는 요청된 순서대로 조회된 문서를 담은 docs 배열을 반환해요. 각 문서는 메타데이터와 소스 데이터를 포함하거나, 문서를 조회할 수 없다면 오류를 포함해요.

응답 본문 필드 (Response body fields)

응답에는 요청된 각 문서에 대한 요소가 하나씩 들어 있는 docs 배열이 있고, 요청과 같은 순서로 반환돼요. 다음 표는 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
docs Array of objects 조회된 문서예요. 각 객체는 하나의 문서를 나타내며 이 표에서 설명하는 필드를 포함해요.
_index String 문서를 담고 있는 인덱스의 이름이에요.
_id String 문서 ID예요.
_version Integer 문서 버전 번호예요. 문서가 업데이트될 때마다 이 번호가 증가해요.
_seq_no Integer 문서가 인덱싱될 때 할당된 시퀀스 번호예요. 낙관적 동시성 제어에 사용돼요.
_primary_term Integer 문서가 인덱싱될 때 할당된 프라이머리 텀(primary term)이에요. 낙관적 동시성 제어를 위해 _seq_no와 함께 사용돼요.
found Boolean 문서가 발견되었는지 여부예요. false이면 문서가 존재하지 않고 _source 필드가 포함되지 않아요.
_source Object 문서의 원본 JSON 콘텐츠예요. found가 false이거나, 요청에서 _source가 false로 설정되었거나, stored_fields가 지정되었다면 생략돼요.
fields Object 문서의 저장된 필드예요. 요청에 stored_fields가 지정되고 found가 true일 때만 포함돼요. 각 필드 값은 배열로 반환돼요.
_routing String 문서를 특정 샤드로 보내는 데 사용한 라우팅 값이에요. 사용자 지정 라우팅 값을 사용한 경우에만 포함돼요.
error Object 실패로 인해 문서를 조회할 수 없을 때의 오류 정보예요. 오류 유형과 이유에 대한 세부 정보를 포함해요.

필요한 권한 (Required permissions)

Security plugin을 사용한다면 indices:data/read/mget 및 indices:data/read/mget* 권한이 있는지 확인하세요.

더 알아보기 (Learn more)