문서 조회 API

문서 조회 API (Get Document API)

인덱스에 저장된 문서를 ID로 조회하고 싶으시죠? 문서 조회 API가 문서 ID로 인덱스에서 JSON 문서와 그 메타데이터를 가져와요. HEAD 요청으로 전체 내용을 가져오지 않고 문서나 그 소스의 존재 여부만 확인할 수도 있어요.

출처: 문서

본문

1.0에서 도입

문서 조회 API는 문서 ID로 인덱스에서 JSON 문서와 그 메타데이터를 검색해요. HEAD 요청으로 전체 내용을 가져오지 않고 문서나 그 소스의 존재 여부를 확인할 수도 있어요.

엔드포인트

인덱스에서 문서와 그 메타데이터를 검색하려면 GET 메서드를 사용해요.

GET /{index}/_doc/{id}

문서 소스만 검색하려면 다음 엔드포인트를 사용해요.

GET /{index}/_source/{id}

문서가 존재하는지 확인하려면 HEAD 메서드를 사용해요.

HEAD /{index}/_doc/{id}
HEAD /{index}/_source/{id}

경로 파라미터

다음 표는 사용 가능한 경로 파라미터예요.

Parameter	Required	Data type	Description
id	Required	String	문서의 고유 식별자예요.
index	Required	String	문서가 포함된 인덱스의 이름이에요.

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터예요. 모든 쿼리 파라미터는 선택적이에요.

Parameter	Methods	Data type	Description	Default
_source	GET	Boolean or List or String	_source 필드를 반환할지 여부예요. 포함하려면 true, 제외하려면 false, 반환할 필드 이름의 쉼표로 구분된 목록을 지정해요. Source filtering을 참고하세요.	N/A
_source_excludes	GET	List or String	응답에서 제외할 소스 필드의 쉼표로 구분된 목록이에요. Source filtering을 참고하세요.	N/A
_source_includes	GET	List or String	응답에 포함할 소스 필드의 쉼표로 구분된 목록이에요. Source filtering을 참고하세요.	N/A
preference	GET, HEAD	String	연산을 처리할 노드나 샤드에 대한 기본 설정이에요. 기본적으로 OpenSearch는 샤드 replica를 무작위로 선택해요. Preference를 참고하세요.	random
realtime	GET, HEAD	Boolean	요청이 실시간인지 여부예요. true면 요청이 문서의 가장 최신 버전을 검색해요. false면 요청은 근실시간이며 마지막 refresh에 기반해 문서를 검색해요. Real-time behavior를 참고하세요.	true
refresh	GET, HEAD	Boolean or String	연산 전에 영향받은 샤드를 refresh해 최근 변경 사항을 표시할지 여부예요. 유효한 값은 다음과 같아요. - false: 영향받은 샤드를 refresh하지 않아요. - true: 영향받은 샤드를 즉시 refresh해요. - wait_for: 응답하기 전에 변경 사항이 표시될 때까지 기다려요. Refresh를 참고하세요.	false
routing	GET, HEAD	List or String	특정 primary 샤드를 대상으로 하는 데 사용되는 라우팅 값이에요. Routing을 참고하세요.	N/A
stored_fields	GET	List or String	반환할 저장 필드(stored fields)의 쉼표로 구분된 목록이에요. 필드를 지정하지 않으면 응답에 저장 필드가 포함되지 않아요. 이 파라미터를 지정하면 _source 파라미터의 기본값이 false예요.	N/A
version	GET, HEAD	Integer	동시성 제어를 위한 명시적 버전 번호예요. 요청이 성공하려면 지정된 버전이 문서의 현재 버전과 일치해야 해요.	N/A
version_type	GET, HEAD	String	동시성 제어를 위한 버전 유형이에요. 유효한 값은 다음과 같아요. - internal: 버전 번호가 OpenSearch에 의해 내부적으로 관리돼요. - external: 버전 번호가 현재 버전보다 커야 해요. - external_gte: 버전 번호가 현재 버전보다 크거나 같아야 해요.	internal

예시 요청

다음 예시는 문서를 ID로 검색해요.

GET /products/_doc/1

예시 응답

다음 예시는 GET 요청의 응답을 보여줘요.

{
  "_index": "products",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "name": "Wireless Mouse",
    "description": "Ergonomic wireless mouse with optical sensor",
    "price": 29.99,
    "category": "Electronics",
    "in_stock": true,
    "manufacturer": "TechCorp",
    "model": "WM-2000",
    "tags": [
      "wireless",
      "ergonomic",
      "optical"
    ]
  }
}

응답 본문 필드

GET 응답에는 다음 필드가 포함돼요.

Field	Data type	Description
_index	String	문서가 포함된 인덱스의 이름이에요.
_id	String	문서의 고유 식별자예요.
_version	Integer	문서의 버전 번호예요. 문서가 업데이트될 때마다 증가해요.
_seq_no	Integer	인덱싱 연산에 대해 문서에 할당된 시퀀스 번호예요. 이전 버전이 새 버전을 덮어쓰지 않도록 보장하는 데 사용돼요.
_primary_term	Integer	인덱싱 연산에 대해 문서에 할당된 primary term이에요. _seq_no와 함께 낙관적 동시성 제어에 사용돼요.
found	Boolean	문서가 존재하는지 여부를 나타내요. 문서를 찾았으면 true, 그렇지 않으면 false예요.
_routing	String	문서를 저장할 샤드를 결정하는 데 사용되는 라우팅 값이에요. 문서를 인덱싱할 때 라우팅 값이 지정된 경우에만 포함돼요.
_source	Object	인덱싱된 원래 JSON 문서예요. _source 파라미터가 false로 설정되거나 stored_fields 파라미터가 사용되면 제외돼요.
_fields	Object	stored_fields 파라미터가 지정될 때 저장된 필드 값을 포함해요. stored_fields가 설정되고 found가 true인 경우에만 반환돼요. 필드 값은 항상 배열로 반환돼요. Retrieving stored fields를 참고하세요.

소스 필터링 (Source filtering)

기본적으로 문서 조회 API는 _source 필드의 전체 내용을 반환해요. 소스의 어떤 부분을 반환할지 제어하거나 완전히 제외할 수 있어요.

소스 검색 비활성화 (Disabling source retrieval)

응답에서 _source 필드를 제외하려면 _source 파라미터를 false로 설정해요. 다음 예시는 소스 내용 없이 문서 메타데이터를 검색해요.

GET /products/_doc/1?_source=false

응답은 _source 필드를 제외해요.

{
  "_index": "products",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true
}

소스 포함 및 제외 (Source includes and excludes)

큰 문서에서 특정 필드만 검색하려면 _source_includes 파라미터로 특정 필드를 포함하거나 _source_excludes 파라미터로 필드를 제외해요. 필요한 데이터만 전송해 네트워크 오버헤드를 줄여요.

다음 예시는 name과 price 필드만 검색해요.

GET /products/_doc/1?_source_includes=name,price

응답의 _source 필드에는 price와 name 필드만 포함돼요.

{
  "_index": "products",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "price": 29.99,
    "name": "Wireless Mouse"
  }
}

짧은 표기법 (Shorter notation)

제외할 필드 없이 특정 필드만 포함하려면 _source 파라미터에 필드를 직접 지정하는 짧은 표기법을 사용해요. 다음 예시는 name과 price 필드만 검색해요.

GET /products/_doc/1?_source=name,price

소스 필드만 검색하기 (Retrieving the source field only)

_source 엔드포인트를 사용해 메타데이터 없이 문서 소스만 검색해요. 다음 예시는 소스 내용만 검색해요.

GET /products/_source/1

응답에는 _source 필드만 포함돼요.

{
  "name": "Wireless Mouse",
  "description": "Ergonomic wireless mouse with optical sensor",
  "price": 29.99,
  "category": "Electronics",
  "in_stock": true,
  "manufacturer": "TechCorp",
  "model": "WM-2000",
  "tags": [
    "wireless",
    "ergonomic",
    "optical"
  ]
}

_source 엔드포인트를 소스 필터링 파라미터와 결합할 수 있어요. 다음 예시는 소스에서 특정 필드만 검색해요.

GET /products/_source/1?_source=name,price

응답에는 price와 name 필드만 포함돼요.

{
  "price": 29.99,
  "name": "Wireless Mouse"
}

_source 엔드포인트에 HEAD를 사용해 문서 소스가 존재하는지 확인할 수 있어요.

HEAD /products/_source/1

응답에는 200 - true만 포함돼요.

라우팅 (Routing)

문서가 사용자 정의 라우팅 값으로 인덱싱된 경우 검색할 때도 같은 라우팅 값을 제공해야 해요. 라우팅 값은 문서를 저장할 샤드를 결정해요.

다음 예시는 라우팅 값 user1로 인덱싱된 문서를 검색해요.

GET /products/_doc/2?routing=user1

응답에는 지정된 라우팅의 문서가 포함돼요.

{
  "_index": "products",
  "_id": "2",
  "_version": 1,
  "_seq_no": 1,
  "_primary_term": 1,
  "_routing": "user1",
  "found": true,
  "_source": {
    "name": "Mechanical Keyboard",
    "description": "RGB mechanical gaming keyboard",
    "price": 149.99,
    "category": "Electronics",
    "in_stock": true,
    "manufacturer": "GameGear",
    "model": "MK-500",
    "tags": [
      "mechanical",
      "rgb",
      "gaming"
    ]
  }
}

올바른 라우팅 값을 지정하지 않으면 OpenSearch는 문서를 찾을 수 없고 found: false 응답을 반환해요.

저장 필드 검색하기 (Retrieving stored fields)

stored_fields 파라미터를 사용해 인덱싱 시점에 인덱스에 저장됐던 특정 필드를 검색해요. 매핑에서 store: true인 필드만 반환돼요. 이 설정이 없는 필드는 무시돼요.

다음 예시는 문서에서 category와 manufacturer 저장 필드만 검색해요.

GET /products/_doc/1?stored_fields=category,manufacturer

저장 필드에서 검색한 필드 값은 항상 배열로 반환된다는 점을 기억하세요. category와 manufacturer는 단일 값 필드지만 배열로 반환돼요.

{
  "_index": "products",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "fields": {
    "category": [
      "Electronics"
    ],
    "manufacturer": [
      "TechCorp"
    ]
  }
}

라우팅으로 인덱싱된 문서에서 저장 필드를 검색할 때는 라우팅 값을 제공해야 해요. 다음 예시는 라우팅 문서에서 저장 필드를 검색해요.

GET /products/_doc/2?routing=user1&stored_fields=category,manufacturer

문서 존재 확인 (Checking document existence)

HEAD 메서드를 사용해 내용을 가져오지 않고 문서가 존재하는지 확인할 수 있어요. OpenSearch는 문서가 존재하면 HTTP 상태 코드 200을, 존재하지 않으면 404를 반환해요.

다음 예시는 문서가 존재하는지 확인해요.

HEAD /products/_doc/1

응답에는 200 - true만 포함돼요.

기본 설정 (Preference)

preference 파라미터는 요청을 처리할 샤드 replica를 제어해요. 기본적으로 OpenSearch는 get 연산을 사용 가능한 샤드 replica에 무작위로 분산해요.

preference 파라미터를 다음 값 중 하나로 설정할 수 있어요.

• _local: 연산을 로컬에 할당된 샤드 replica로 보내 네트워크 오버헤드를 줄여요.
• 사용자 정의 문자열 값: 같은 사용자 정의 값을 가진 요청을 같은 샤드 replica로 라우팅해요. 이는 샤드가 서로 다른 refresh 상태에 있을 때 일관된 결과를 보장해요. 일반적인 사용자 정의 값은 세션 ID나 사용자 이름이에요.

실시간 동작 (Real-time behavior)

기본적으로 문서 조회 API는 실시간으로 작동해 인덱스 refresh 빈도와 무관하게 문서의 최신 버전을 검색해요. 즉, 인덱스가 검색 가능하도록 refresh되기 전이라도 인덱싱 직후 문서를 검색할 수 있어요.

저장 필드를 요청하고(stored_fields 파라미터 사용) 문서가 업데이트됐지만 아직 refresh되지 않은 경우, OpenSearch는 문서 소스를 파싱하고 분석해 요청된 저장 필드를 추출해요.

실시간 동작을 비활성화하고 인덱스의 마지막 refresh 상태에 기반해 문서를 검색하려면 realtime 파라미터를 false로 설정해요.

Refresh

refresh 파라미터를 true로 설정해 문서를 검색하기 전에 관련 샤드를 refresh할 수 있어요. refresh는 최근 변경 사항을 검색 가능하게 하지만 상당한 시스템 부하를 일으키고 인덱싱을 느리게 할 수 있어요. 이 파라미터를 활성화하기 전에 데이터 신선도와 성능 사이의 트레이드오프를 신중히 평가하세요.

버전 관리 (Versioning)

version 파라미터를 사용해 문서의 현재 버전이 지정된 숫자와 일치할 때만 문서를 검색할 수 있어요. 이는 버전 관리된 문서로 작업할 때 데이터 일관성을 보장해요.

내부적으로 OpenSearch는 문서가 업데이트될 때 이전 문서 버전을 삭제된 것으로 표시하고 완전히 새 문서 버전을 만들어요. 문서 조회 API로 이전 버전에 접근할 수는 없지만, OpenSearch는 인덱싱 중에 삭제된 버전을 백그라운드에서 자동으로 정리해요.

분산 모델 (Distributed model)

문서 조회 API는 문서 ID를 사용해 문서를 저장하는 샤드를 식별하는 해시 값을 계산해요. 그런 다음 OpenSearch는 해당 샤드 그룹의 replica 중 하나(primary 샤드와 그 replica 포함)로 요청을 라우팅하고 결과를 반환해요.

샤드 replica가 많을수록 부하가 여러 replica에 분산되므로 조회 요청 처리량이 늘어나 GET 연산의 확장성이 향상돼요.

보안

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

더 알아보기 (Learn more)

• _source 엔드포인트와 _source_includes로 필요한 필드만 가져와 부하를 줄일 수 있어요.
• 라우팅된 문서는 같은 라우팅 값을 제공해야 조회할 수 있어요.