Elasticsearch - 데이터처리¶
본 포스팅의 모든 실습과 예제는 Elasticsearch 7.6 버전을 기준으로 작성되었다.
지난 1편에서 클러스터와 역인덱스 기본 개념을 다루었으니, 이번에는 REST API를 이용해 데이터를 추가·수정·삭제(CRUD)하고, 대량 데이터를 적재하는 벌크(Bulk) API 및 기본 검색 방법에 대해 알아본다.
1. Docker를 이용한 Elasticsearch 로컬 환경 구축¶
본격적인 실습에 앞서 Docker를 이용해 싱글 노드(Single-Node) 개발 환경을 1분 만에 구축해 보자.
# 1. Elasticsearch 7.6.2 이미지 다운로드
docker pull elasticsearch:7.6.2
# 2. 싱글 노드 컨테이너 실행
docker run -d \
-p 9200:9200 -p 9300:9300 \
-e "discovery.type=single-node" \
--name elastic_7_6 \
elasticsearch:7.6.2
컨테이너가 정상 기동되었는지 클러스터 기본 정보를 조회하여 확인한다:
curl -X GET 'localhost:9200/_all?pretty'
2. 도큐먼트 기본 CRUD 처리¶
2.1 데이터 추가 (POST vs PUT vs _create)¶
Elasticsearch는 HTTP POST 또는 PUT 메서드를 사용하여 JSON 형식의 도큐먼트를 생성한다.
① 특정 ID를 지정하여 생성 (POST / PUT)¶
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/user/_doc/1' -d '
{ "name": "hong-gil-dong", "birth": 1988, "gender": "male" }'
/* 반환 결과 */
{
"_index": "user",
"_type": "_doc",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": { "total": 2, "successful": 1, "failed": 0 },
"_seq_no": 0,
"_primary_term": 1
}
② 자동 ID 생성 (POST 전용)¶
ID를 생략하고 POST를 호출하면 Elasticsearch가 고유한 임의의 해시 문자열을 _id로 자동 부여한다. (단, ID 없는 PUT 요청은 405 Method Not Allowed 에러가 발생한다.)
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/user/_doc' -d '
{ "name": "kim-su-mi", "birth": 1949, "gender": "female" }'
③ 기존 도큐먼트 덮어쓰기 (Overwrite)¶
이미 존재하는 ID(1)로 다시 데이터를 전송하면 기존 도큐먼트를 통째로 대체하며, result가 updated로 바뀌고 _version이 1 증가한다.
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/user/_doc/1' -d '
{ "name": "hong-gil-dong2", "birth": 1990, "gender": "male" }'
④ 중복 방지 생성 (_create 엔드포인트)¶
기존 데이터를 덮어쓰지 않고 오직 새로 생성할 때만 허용하고 싶다면 _create를 사용한다. 이미 존재하는 ID로 호출 시 충돌(409 Conflict) 오류가 발생한다.
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/user/_create/2' -d '
{ "name": "hong-gil-dong2", "birth": 2000, "gender": "male" }'
2.2 데이터 삭제 (DELETE)¶
① 단일 도큐먼트 삭제¶
curl -X DELETE 'localhost:9200/user/_doc/2'
💡 버전(version) 동작 원리:
도큐먼트를 삭제한 후 동일한 ID(2)로 다시 도큐먼트를 생성하면_version이 1이 아니라 삭제 직전 버전에서 증가한 값(예: 3)으로 생성된다. 이는 내부적으로 즉시 디스크에서 삭제되는 것이 아니라, 삭제 마킹 후 백그라운드 세그먼트 병합(Merge) 시점에 물리 삭제되기 때문이다.
② 인덱스 전체 삭제¶
curl -X DELETE 'localhost:9200/user'
인덱스를 삭제하면 해당 인덱스 내의 모든 도큐먼트와 샤드가 완전히 제거되며, 이후 다시 생성할 때는 버전이 1부터 시작된다.
2.3 데이터 수정 (_update API)¶
도큐먼트 전체를 덮어쓰지 않고 특정 필드만 부분 수정하거나 신규 필드를 추가할 때는 _update API를 사용한다.
① 부분 필드 수정 (doc 키 사용)¶
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/user/_update/1' -d '
{
"doc": {
"birth": 2020,
"locale": "ko-KR"
}
}'
_update API는 내부적으로 기존 도큐먼트를 읽어와(GET) 변경된 필드를 병합한 후 새로운 도큐먼트로 다시 색인하는 방식으로 동작한다.
② 스크립트 기반 연산 수정 (Painless Script)¶
script 블록을 활용하면 기존 필드 값에 산술 연산을 적용하거나 동적 로직을 수행할 수 있다:
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/user/_update/1' -d '
{
"script": {
"source": "ctx._source.birth += params.count",
"lang": "painless",
"params": { "count": 10 }
}
}'
위 스크립트 실행 후 birth 필드 값은 기존 2020에서 10이 더해진 2030으로 변경된다.
3. 대규모 데이터 적재를 위한 벌크 API (_bulk)¶
대량의 도큐먼트를 1건씩 HTTP로 요청하면 네트워크 오버헤드로 인해 색인 속도가 심각하게 저하된다.
Elasticsearch의 _bulk API를 사용하면 수백~수천 건의 작업을 하나의 요청으로 묶어 고속으로 처리할 수 있다.
3.1 벌크 포맷 규칙 (NDJSON)¶
벌크 API는 명령 메타데이터 줄과 실제 데이터 줄이 한 쌍을 이루는 NDJSON(Newline Delimited JSON) 형식을 따른다:
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/_bulk' -d'
{ "index" : { "_index" : "user_bulk", "_id" : "1" } }
{ "first_name" : "James", "last_name": "Butt", "birth": 1970, "country": "New Orleans", "zip": "70116" }
{ "index" : { "_index" : "user_bulk", "_id" : "2" } }
{ "first_name" : "Josephine", "last_name": "Darakjy", "birth": 1967 , "country": "Livingston", "zip": "48116" }
{ "index" : { "_index" : "user_bulk", "_id" : "3" } }
{ "first_name" : "Art", "last_name": "Venere", "birth": 1977, "country": "Gloucester", "zip": "8014" }
'
3.2 JSON 파일로부터 벌크 적재¶
파일로 저장된 대용량 데이터를 적재할 때는 --data-binary 옵션을 사용한다:
curl -H 'Content-Type: application/x-ndjson' \
-X POST 'localhost:9200/_bulk' \
--data-binary "@user_bulk_file.json"
4. 데이터 조회와 검색 기초 (Search Basics)¶
Elasticsearch의 검색 인터페이스는 크게 URI 검색과 리퀘스트 바디(Request Body) 검색으로 나뉜다.
4.1 URI 검색 (간이 쿼리)¶
URL 쿼리 파라미터로 간단한 검색 명령을 전달하는 방식이다. 터미널이나 웹 브라우저에서 빠르게 확인할 때 유용하다.
① 기본 검색 (q 파라미터)¶
# country 필드가 Anchorage인 도큐먼트 검색
curl -X GET 'localhost:9200/user_bulk/_search?pretty&q=country:Anchorage'
② 필드 지정 검색(df)과 기본 연산자(default_operator)¶
# 기본적으로 띄어쓰기는 OR로 동작 (San 또는 Diego 검색 ➡️ San Francisco도 함께 나옴)
curl -X GET 'localhost:9200/user_bulk/_search?pretty&q=San%20Diego&df=country'
# AND 조건으로 정확히 일치시키려면 default_operator=AND 지정 필요
curl -X GET 'localhost:9200/user_bulk/_search?pretty&q=San%20Diego&df=country&default_operator=AND'
③ 메타데이터만 확인 (_source=false)¶
도큐먼트 본문 내용 없이 매칭된 전체 개수(hits.total)와 점수(max_score)만 빠르게 확인할 때 사용한다:
curl -X GET 'localhost:9200/user_bulk/_search?pretty&q=country:Anchorage&_source=false'
④ 정렬과 페이징 (sort, from, size)¶
# birth 오름차순 기준, 1번째(0부터 시작) 인덱스부터 2건 조회
curl -X GET 'localhost:9200/user_bulk/_search?pretty&sort=birth:asc&from=1&size=2'
4.2 리퀘스트 바디 검색 (Request Body & Query DSL)¶
실무에서 복잡하고 정교한 검색 쿼리를 작성할 때는 반드시 HTTP Body에 JSON을 실어 보내는 리퀘스트 바디 검색(Query DSL)을 사용한다.
① 기본 구조 및 match 쿼리¶
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/user_bulk/_search?pretty' -d '
{
"query": {
"match": { "country": "Anchorage" }
}
}'
② 페이징 및 다중 정렬 적용¶
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/user_bulk/_search?pretty' -d '
{
"from": 1,
"size": 2,
"sort": [
{ "birth": "asc" }
]
}'
③ 검색어 하이라이팅 (highlight)¶
검색 결과 텍스트에서 매칭된 검색어 부분을 <em>...</em> 태그로 감싸서 반환받을 수 있어 UI 검색 화면 구현에 필수적이다:
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/user_bulk/_search?pretty' -d '
{
"query": {
"match": { "country": "San" }
},
"highlight": {
"fields": {
"country": {}
}
}
}'
/* 하이라이트 결과 예시 */
"highlight": {
"country": [
"<em>San</em> Francisco"
]
}
마치며¶
이번 글에서는 Docker를 이용한 로컬 환경 구축, HTTP 메서드를 활용한 Document CRUD 및 _update API, 대규모 적재를 위한 _bulk API, 그리고 URI와 리퀘스트 바디를 활용한 검색 기초를 폭넓게 살펴보았다.
다음 포스팅에서는 리퀘스트 바디 검색의 꽃인 Query DSL의 match, term, range, bool 등 실전 고급 검색 쿼리를 집중적으로 다룰 예정이다.