본문으로 건너뛰기

인덱스 생성을 위한 데이터 업로드

Advanced Managed Search(OpenSearch)에서는 문서를 업로드(색인)하는 과정에서 인덱스가 자동으로 생성됩니다. 이 문서에서는 OpenSearch API를 사용하여 단일 문서 업로드와 대량 문서 업로드(Bulk) 방법을 설명합니다.

사전 준비 사항​

데이터 업로드를 시작하기 전에 다음 사항을 확인하세요.

  • Advanced Managed Search 클러스터가 정상 상태(Running) 인지 확인
  • 클러스터 상세 페이지에서 엔드포인트 확인
  • 클러스터 생성 시 설정한 마스터 사용자 계정 정보 준비
  • OpenSearch API 요청을 수행할 수 있는 환경(curl 등)

인덱스 이름 명명 규칙​

OpenSearch에서 인덱스를 생성할 때는 다음 명명 규칙을 준수해야 합니다.

  • 인덱스 이름은 소문자(a–z) 로만 구성해야 합니다.
  • 공백( )을 포함할 수 없습니다.
  • 다음 특수 문자는 사용할 수 없습니다.
    \ / * ? " < > | , #
  • .(점) 또는 .. 단독 이름은 사용할 수 없습니다.
  • 인덱스 이름은 _, -, 숫자(0–9)를 포함할 수 있습니다.
  • 최대 길이는 255자입니다.
안내

인덱스 이름은 URL 경로의 일부로 사용되므로, 명명 규칙을 위반할 경우 문서 업로드 요청이 실패할 수 있습니다.

단일 문서 업로드(색인)하기​

OpenSearch는 REST API를 통해 단일 문서를 업로드할 수 있으며, 문서를 업로드하면 지정한 인덱스가 존재하지 않을 경우 자동으로 생성됩니다.

curl -X PUT "https://<cluster-endpoint>/movies/_doc/1" \
-u '<master-user>:<password>' \
-H "Content-Type: application/json" \
-d '{
  "title": "The Matrix",
  "year": 1999,
  "genre": "Sci-Fi"
}'
항목설명
movies인덱스 이름
_doc문서 API 엔드포인트
1문서 고유 ID
요청 본문(JSON)인덱싱할 문서 데이터

요청이 성공하면 문서는 OpenSearch에 저장되며 즉시 검색 가능한 상태가 됩니다.

대량 문서 업로드(Bulk)하기​

curl -X POST "https://<cluster-endpoint>/_bulk" \
-u '<master-user>:<password>' \
-H "Content-Type: application/x-ndjson" \
-d '
{ "index": { "_index": "movies", "_id": "2" } }
{ "title": "Inception", "year": 2010, "genre": "Sci-Fi" }
{ "index": { "_index": "movies", "_id": "3" } }
{ "title": "Interstellar", "year": 2014, "genre": "Sci-Fi" }
'
  • Bulk 요청은 액션 메타데이터 라인과 문서 데이터 라인을 번갈아 작성합니다.
  • 각 JSON 객체는 반드시 개행 문자(\n)로 구분되어야 합니다.
안내

Bulk API 요청의 마지막 줄에도 개행 문자가 포함되어야 하며, 형식이 올바르지 않을 경우 요청이 실패할 수 있습니다.

데이터 업로드 확인하기​

업로드한 데이터는 다음 방법으로 확인할 수 있습니다.

  • OpenSearch Dashboards에 접속하여 인덱스 및 문서 확인
  • 검색 API를 사용하여 문서 조회
curl -X GET "https://<cluster-endpoint>/movies/_search" \
-u '<master-user>:<password>'