Elasticsearch REST API를 사용한 문서 인덱싱 및 업데이트

Elasticsearch는 잘 구조화된 데이터 수집에 의존하는 강력하고 분산된 검색 및 분석 엔진입니다. 이 데이터를 관리하는 것은 주로 다재다능한 REST API를 통해 실행되는 기본적인 생성, 읽기, 업데이트 및 삭제(CRUD) 작업을 포함합니다. 새로운 문서를 올바르게 인덱싱하고 기존 문서를 효율적으로 업데이트하는 방법을 이해하는 것은 실시간으로 정확한 데이터 스토어를 유지하는 데 중요합니다.

이 가이드는 Elasticsearch 클러스터 내에서 새 레코드를 인덱싱하고 기존 문서를 수정하는 데 사용되는 필수 HTTP 메서드 및 API 엔드포인트를 안내합니다. 원활한 데이터 관리를 보장하기 위해 구문, 필요한 JSON 페이로드 및 응답 코드 해석에 중점을 둘 것입니다.

전제 조건

진행하기 전에 다음을 확인하십시오.

활성 Elasticsearch 클러스터가 실행 중일 것.
HTTP 요청을 수행할 수 있는 명령줄 도구(curl 등) 또는 HTTP 클라이언트(Postman 등).
대상 인덱스 이름을 알고 있을 것.

1. 새 문서 인덱싱

인덱싱은 JSON 문서를 Elasticsearch 인덱스에 저장하는 과정입니다. Elasticsearch는 명시적으로 ID가 제공되지 않는 한 문서에 고유 ID를 자동으로 할당합니다. 인덱싱을 위한 주요 방법은 PUT 또는 POST HTTP 메서드입니다.

1.1 자동 ID로 인덱싱 (`POST`)

인덱스 엔드포인트에 POST를 사용할 때 Elasticsearch는 고유한 문서 ID를 생성합니다. 이는 ID가 내부적으로 관리될 때 초기 데이터 수집에 종종 선호되는 방법입니다.

엔드포인트: POST /{index_name}/_doc/

예시 요청 (curl 사용):

curl -X POST "localhost:9200/products/_doc/" -H 'Content-Type: application/json' -d'
{
  "name": "Wireless Mouse X1",
  "price": 25.99,
  "in_stock": true
}
'

성공적인 응답 스니펫:

{
  "_index": "products",
  "_id": "c7BwJ3gBpV4wT-eH_aY1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

created를 보여주는 result 필드는 새 문서가 추가되었음을 확인합니다.

1.2 특정 ID로 인덱싱 (`PUT`)

소스 시스템에서 문서에 대한 고유 식별자를 제공하는 경우, 특정 ID를 대상으로 하는 PUT 메서드를 사용해야 합니다. 해당 ID를 가진 문서가 이미 존재하는 경우, PUT은 전체 문서를 덮어씁니다.

엔드포인트: PUT /{index_name}/_doc/{document_id}

예시 요청: ID 1001을 가진 문서 인덱싱.

curl -X PUT "localhost:9200/products/_doc/1001" -H 'Content-Type: application/json' -d'
{
  "name": "Mechanical Keyboard K90",
  "price": 129.99,
  "in_stock": true
}
'

성공적인 응답 스니펫:

{
  "_index": "products",
  "_id": "1001",
  "_version": 1,
  "result": "created",
  "_shards": { ... }
}

덮어쓰기에 대한 팁: 동일한 ID로 정확히 동일한 PUT 요청을 다시 실행하면 result가 updated로 변경되고 _version 번호가 증가합니다.

2. 기존 문서 업데이트

문서 업데이트는 덮어쓰기와 다릅니다. 변경되지 않은 필드에 영향을 주지 않고 기존 문서 내의 특정 필드만 변경하려면 일반적으로 POST 메서드와 함께 _update 엔드포인트를 사용합니다.

2.1 `_update`를 사용한 부분 업데이트

_update API는 원자적 업데이트(Atomic Updates)에 매우 중요합니다. 이는 페이로드 내에 doc 블록을 필요로 하며, 이 블록에는 수정하려는 필드만 포함됩니다. Elasticsearch는 문서를 검색하고, 변경 사항을 병합한 다음 다시 인덱싱합니다.

엔드포인트: POST /{index_name}/_update/{document_id}

예시 시나리오: 제품 ID 1001의 가격을 $129.99에서 $119.99로 업데이트하고 품절로 표시하려고 합니다.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "doc": {
    "price": 119.99,
    "in_stock": false
  }
}
'

성공적인 응답 스니펫:

{
  "_index": "products",
  "_id": "1001",
  "_version": 2, 
  "result": "updated",
  "_shards": { ... }
}

_version이 1에서 2로 증가하여 수정 사항을 반영하는 것을 확인하십시오.

2.2 스크립트 업데이트 사용

더 복잡하거나 조건부 또는 수학적 업데이트를 위해 Elasticsearch는 _update API 내에서 Painless 스크립팅을 지원합니다. 이를 통해 카운터 증가 또는 현재 값에 기반한 필드 설정과 같은 작업을 수행할 수 있습니다.

예시 시나리오: 문서 ID 1001에 대해 재고 수량을 5만큼 증가시킵니다.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "script": {
    "source": "ctx._source.stock += params.count",
    "params": {
      "count": 5
    }
  }
}
'

주요 스크립팅 개념: ctx._source는 현재 문서 소스를 참조합니다.

스크립트 경고: 강력하지만 복잡한 스크립트는 성능에 영향을 줄 수 있습니다. 가능하면 일반적으로 더 빠르고 안전한 간단한 필드 업데이트(doc)를 사용하십시오.

3. 대량 인덱싱 및 업데이트

대량의 데이터 작업의 경우, 각 문서에 대해 개별 요청을 보내는 것은 비효율적입니다. Elasticsearch는 단일 요청으로 여러 인덱싱, 업데이트 또는 삭제 작업을 처리하는 _bulk API를 제공합니다.

3.1 대량 요청의 구조

대량 요청은 특정 줄 바꿈으로 구분된 JSON(NDJSON) 형식을 사용합니다. 각 작업은 메타데이터 줄(액션, 인덱스 및 선택적 ID 지정)로 정의되며, 그 뒤에 문서 소스(필요한 경우)가 즉시 따릅니다.

대량 작업 유형: index, create, update, delete.

대량 요청 예시 (인덱싱 및 업데이트 혼합):

curl -X POST "localhost:9200/products/_bulk" -H 'Content-Type: application/x-ndjson' -d'

{"index": {"_id": "2001"}}
{"name": "USB-C Hub", "price": 45.00, "in_stock": true}
{"update": {"_id": "1001"}}
{"doc": {"price": 115.00}}
{"delete": {"_id": "3003"}}

'

이 예시에서:

문서 2001이 인덱싱됩니다.
문서 1001이 부분적으로 업데이트됩니다 (가격이 인하됩니다).
문서 3003이 삭제됩니다.

대량 응답: 응답은 배치 내의 각 개별 작업의 성공 또는 실패를 상세히 보여주므로, 어떤 문서가 성공하고 어떤 문서가 실패했는지 정확히 파악할 수 있습니다.

주요 API 명령어 요약

작업	HTTP 메서드	엔드포인트 패턴	효과
인덱싱 (자동 ID)	`POST`	`/{index}/_doc/`	자동 생성된 ID로 새 문서를 생성합니다.
인덱싱/덮어쓰기	`PUT`	`/{index}/_doc/{id}`	지정된 ID에 문서를 생성하거나 완전히 교체합니다.
부분 업데이트	`POST`	`/{index}/_update/{id}`	`doc` 블록에 지정된 변경 사항을 병합합니다.
대량 작업	`POST`	`/{index}/_bulk`	단일 요청으로 여러 작업을 실행합니다.

이러한 기본적인 REST API 상호 작용을 숙달하는 것은 모든 Elasticsearch 애플리케이션 내에서 동적 데이터 관리의 기반을 제공합니다.

Elasticsearch REST API를 사용한 문서 인덱싱 및 업데이트

전제 조건

1. 새 문서 인덱싱

1.1 자동 ID로 인덱싱 (POST)

1.2 특정 ID로 인덱싱 (PUT)

2. 기존 문서 업데이트

2.1 _update를 사용한 부분 업데이트

2.2 스크립트 업데이트 사용

3. 대량 인덱싱 및 업데이트

3.1 대량 요청의 구조

주요 API 명령어 요약

1.1 자동 ID로 인덱싱 (`POST`)

1.2 특정 ID로 인덱싱 (`PUT`)

2.1 `_update`를 사용한 부분 업데이트