09. 문서관리 API(Document API)
엘라스틱서치에서 제공하는 대표적인 Document API
Index API : 문서를 생성
Get API : 문서를 조회
Delete API : 문서를 삭제
Update API : 문서를 수정
Bulk API : 대량의 문서를 처리
Reindex API : 문서를 복사
1. 문서 파라미터
| _id | 문서를 생성할 때 기본적으로 ID가 반드시 필요하다. 문서 추가 시 ID를 지정하지 않으면 엘라스틱서치가 자동으로 ID를 부여한다. (UUID 형태의 값) |
| _version | 색인된 모든 문서는 버전 값을 가지고 있다. 기본적으로 버전은 1부터 시작해서 도큐먼트가 갱신/삭제될 때마다 증가한다. 직접 버전 값을 입력할 수 있으나 반드시 정숫값이어야 한다. |
| op_type | 일반적으로 ID 존재 시 update, 미존재 시 create 작업이 일어난다. Index API를 호출할 때 op_type 파라미터를 이용하면 수행되는 작업의 유형을 강제로 지정할 수 있다. 예) PUT movie_dynamic/_doc/1?op_type=create { ... } |
| timeout | 대기 시간을 조절한다. (기본값 : 1분) 예) PUT movie_dynamic/_doc/1?timeout=5m { ... } |
2. Index API
문서를 특정 인덱스에 추가하는 데 사용됩니다.
# 요청
PUT movie_dynamic/_doc/1
{
"movieCd": "20173732",
"movieNm": "살아남은 아이",
"movieNmEn": "Last Child",
"typeNm": "장편"
}
# 결과
{
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": { # 몇 개의 샤드에서 명령이 수행됐는지에 대한 정보
"total": 2, # 복제돼야 하는 전체 샤드 개수
"successful": 1, # 성공적으로 복제된 샤드 개수
"failed": 0 # 복제에 실패한 샤드 건수
},
"_seq_no": 0,
"_primary_term": 1
}> Index API는 최소 한 개 이상의 successful 항목이 있어야 성공한 것으로 간주합니다.
3. Get API
특정 문서를 인덱스에서 조회할 때 사용하는 API입니다. 조회하고자 하는 문서의 ID를 명시적으로 지정해서 사용합니다. 일반적으로 조회되는 문서의 내용은 _source 항목으로 확인할 수 있습니다.
# 요청
GET movie_dynamic/_doc/1
# _source_exclude 옵션 : 제외할 필드명 지정
# 예 : GET movie_dynamic/_doc/1?_source_exclude=movieNm
# 결과
{
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "1",
"_version": 1,
"found": true,
"_source": {
"movieCd": "20173732",
"movieNm": "살아남은 아이",
"movieNmEn": "Last Child"
}
}
4. Delete API
문서를 삭제하는 API입니다. result 항목에 "deleted" 값이 반환되며 version 값이 1만큼 증가합니다.
DELETE movie_dynamic/_doc/1특정 문서가 아니라 인덱스 전체를 삭제하고 싶을 때는 인덱스명을 입력하면 됩니다.
DELETE movie_dynamic특정 인덱스에서 검색을 수행한 후 그 결과에 해당하는 문서만 삭제하고 싶을 경우 Delete By Query API를 사용하면 됩니다.
# 요청
POST movie_dynamic/_delete_by_query
{
"query": {
"term": {
"movieCd": "20173732"
}
}
}
# 결과
{
"took": 42,
"timed_out": false,
"total": 1,
"deleted": 1,
"batches": 1,
"version_conflicts": 0,
"noops": 0,
"retries": {
"bulk": 0,
"search": 0
},
"throttled_millis": 0,
"requests_per_second": -1,
"throttled_until_millis": 0,
"failures": []
}
5. Update API
스크립트를 바탕으로 문서를 수정할 수 있습니다.(Scripting) 스크립트를 통해 "ctx._source.필드명"과 같은 형태로 접근할 수 있습니다. Update API가 호출되면 엘라스틱서치는 Index에서 문서를 가져와 스크립트를 수행한 후, 이를 다시 재색인(Reindex)합니다. 이러한 원리로 Update API를 사용하기 위해서는 _source 필드가 활성화돼 있어야 하며, ctx 필드에서는 _source 변수뿐 아니라 _index, _type, _id, _version, _routing, _now 등 추가적인 변수도 사용할 수 있습니다.
Update API를 이용해 counter 값을 1만큼 증가시키는 예제입니다.
POST movie_dynamic/_doc/1/_update
{
"script" : {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params" : {
"count" : 1
}
}
}# 필드 추가
POST movie_script/_doc/1/_update
{
"script": "ctx._source.movieList.Black_Panther = 3.7"
}
# 필드 제거
POST movie_script/_doc/1/_update
{
"script": "ctx._source.movieList.remove(\"Suits\")"
}[참고]
엘라스틱서치에서 스크립팅을 사용하는 두 가지 방법이 있습니다.
1) config 폴더에 스크립팅을 저장하는 방식: 스크립트 파일을 config 폴더에 저장한 다음 이름을 지정해 코드에서 호출한다.
2) In-request 방식: 동적 스크립팅이라고 하며 API를 호출할 때 코드 내에서 스크립트를 직접 정의해서 사용한다.
일반적으로 동적 스크립팅 방식이 많이 사용됩니다. 동적 스크립팅 기능을 사용하려면 elasticsearch.yml 파일에 다음과 같은 설정을 추가해야 합니다.
script.disable_dynamic: false
6. Bulk API
Get/Delete/Update API는 한 번에 하나의 문서만을 대상으로 동작합니다. 하지만 Bulk API를 이용하면 한 번의 API 호출로 다수의 문서를 색인하거나 삭제할 수 있습니다. 대량 색인이 필요한 경우 bulk API를 사용하는 것 이 좋습니다. 단, 여러 건의 데이터 처리 중 실패가 발생하더라도 롤백되지 않습니다.
# 요청
POST _bulk
{ "index" : { "_index" : "movie_dynamic", "_type" : "_doc", "_id" : "1" } }
{ "title" : "살아남은 아이" }
{ "delete" : { "_index" : "movie_dynamic", "_type" : "_doc", "_id" : "2" } }
{ "create" : { "_index" : "movie_dynamic", "_type" : "_doc", "_id" : "3" } }
{ "title" : "프렌즈: 몬스터섬의비밀" }
{ "update" : {"_index" : "movie_dynamic", "_type" : "_doc", "_id" : "1"} }
{ "doc" : {"movieNmEn" : "Last Child"} }
# 결과
{
"took": 311,
"errors": false,
"items": [
{
"index": {
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 201
}
},
{
"delete": {
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "2",
"_version": 1,
"result": "not_found",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 404
}
},
{
"create": {
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "3",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 201
}
},
{
"update": {
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "1",
"_version": 2,
"result": "updated",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 1,
"_primary_term": 1,
"status": 200
}
}
]
}
# 요청
GET movie_dynamic/_search
# 결과
{
"took": 2,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 2,
"max_score": 1,
"hits": [
{
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "1",
"_score": 1,
"_source": {
"title": "살아남은 아이",
"movieNmEn": "Last Child"
}
},
{
"_index": "movie_dynamic",
"_type": "_doc",
"_id": "3",
"_score": 1,
"_source": {
"title": "프렌즈: 몬스터섬의비밀"
}
}
]
}
}
7. Reindex API
Reindex API를 사용하는 가장 일반적인 상황은 한 인덱스에서 다른 인덱스로 문서를 복사할 때 사용합니다.
POST _reindex
{
"source": { # 복사할 인덱스
"index": "movie_dynamic"
},
"dest": { # 복사될 인덱스
"index": "movie_dynamic_new",
"version_type": "internal"
}
}특정 조회 결과와 일치하는 문서만 복사하고 싶은 경우 source 항목에 쿼리를 포함시키면 됩니다.
POST _reindex
{
"size": 10000, # 기본적으로 Reindex API는 1,000건 단위로 스크롤을 수행
"source": {
"index": "movie_dynamic",
"sort": { #정렬#
"counter": "desc"
}
"type": "_doc",
"query": {
"term": {
"title.keyword": "프렌즈: 몬스터섬의비밀"
}
}
},
"dest": {
"index": "movie_dynamic_new"
}
}