<div id="readability-page-1" class="page"><p><cite>시뻘건볼때기</cite>
                <span> 2023. 12. 13. 22:46</span>
              </p><div>
                                <p data-ke-size="size16">인덱스를 활용하기 위해서는 Document api를 사용할 수 있다. 엘라스틱서치에서는 인덱스 관리를 위해 Document api를 제공하는데 이를 이용해 문서를 조회하거나 추가/수정/삭제 등의 작업을 할 수 있다.</p>

<h2 data-ke-size="size26"><b>문서 파라미터</b></h2>
<p data-ke-size="size16">Document api에서는 다양한 파라미터를 지원한다. 이러한 파라미터는 Document api에서 공통적으로 사용할 수 있다.</p>

<h3 data-ke-size="size23">문서 ID 자동생성</h3>
<p data-ke-size="size16">문서를 생성할 때는 각 문서를 구분하기 위해 ID가 반드시 필요하다. 만약 문서를 추가할 때 ID를 지정하지 않으면 엘라스틱서치가 자동으로 부여한다. 자동으로 생성되는 ID는 UUID 형태의 값으로 생성된다.</p>

<h3 data-ke-size="size23">버전 관리</h3>
<p data-ke-size="size16">색인된 모든 문서는 버전 값을 가지고있다. 버전 정보는 색인할 때 결과에 포함된다. 최초 1을 갖게되고 문서를 변경할 때마다 증가한다. Update api를 이용할 경우 내부적으로 snapshot을 생성해서 문서를 수정하고 인덱스에 다시 재색인하게되는데 이때 버전 정보를 이용한다.</p>

<h3 data-ke-size="size23">오퍼레이션 타입</h3>
<p data-ke-size="size16">일반적으로 ID가 이미 존재하는 경우에는 update 작업이 일어나고, ID가 없을 경우에는 create 작업이 일어난다. update 작업이 일어날 때 데이터가 존재할 경우 update하지 않고 색인이 실패하길 원한다면 op_type을 이용할 수 있다. index api를 호출할 때 op_type 파라미터를 이용하면 수행되는 작업의 유형을 강제로 지정할 수 있다.&nbsp;</p>
<pre id="code_1702472653016" data-ke-language="bash" data-ke-type="codeblock"><code>PUT movie_dynamic/_doc/1?op_type=create
{
	"movieCd": "20173732",
	"movieNm": "살아남은 아이",
	"movieNmEn": "Last Child",
	"typeNm":"단편"
}



{
	"error": {
		"root_cause": [
			{
				"type": "version_conflict_engine_exception",
				"reason": "[_doc][1]: version conflict, document already exists (current version [1])",
				"index_uuid": "394eLiPOTb6qUI9fftvHfw",
				"shard": "3",
				"index": "movie_dynamic"
			}
		],
			"type": "version_conflict_engine_exception",
            "reason": "[_doc][1]: version conflict, document already exists (current version [1])",
            "index_uuid": "394eLiPOTb6qUI9fftvHfw",
            "shard": "3",
            "index": "movie_dynamic"
	},
	"status": 409
}</code></pre>

<h3 data-ke-size="size23">타임아웃 설정</h3>
<p data-ke-size="size16">이미 색인 작업이 진행 중인 동안 추가적으로 색인 api가 호출될 경우에는 일정 기간 대기하게된다. 기본적으로 1분간 대기하게되는데 1분이 지날 경우에는 요청 자체가 실패한다. 이때 timeout 파라미터를 설정해서 대기 시간을 조정할 수 있다.</p>
<pre id="code_1702473109054" data-ke-language="bash" data-ke-type="codeblock"><code># 5분간 다른 색인 api가 완료되기를 기다린다.
PUT movie_dynamic/_doc/1?timeout=5m
{
	"movieCd": "20173732",
	"movieNm": "살아남은 아이",
	"movieNmEn": "Last Child",
	"typeNm":"단편"
}</code></pre>

<h3 data-ke-size="size23">인덱스 맵핑 정보 자동 생성</h3>
<p data-ke-size="size16">색인할 때 기존에 정의되지 않은 필드의 정보가 존재할 경우 기본적으로는 동적 맵핑을 허용하기 때문에 색인 즉시 새로운 필드가 생성된다. 동적 맵핑을 허용할 경우 원치 않는 오류가 발생할 수 있기 때문에 비활성화를 염두해두어야한다.</p>
<ul data-ke-list-type="disc">
<li>action.auto_create_index: 인덱스 자동 생성 여부를 설정한다. 기본 값은 true</li>
<li>index.mapper.dynamic: 동적 맵핑 사용 여부를 설정한다. 기본 값은 true</li>
</ul>

<h2 data-ke-size="size26">index api</h2>
<p data-ke-size="size16">문서를 특정 인덱스에 추가할 때 사용한다. 새로 추가된 문서는 버전 값으로 1이 부여되며 업데이트 될 때마다 +1 증가한다.</p>

<h2 data-ke-size="size26">get api</h2>
<p data-ke-size="size16">특정 문서를 인덱스에서 조회할 때 사용한다. 조회하고자 하는 문서의 ID를 명시적으로 지정해서 사용한다. 일반적으로 조회되는 문서의 내용은 _source 항목으로 확인할 수 있다.</p>
<pre id="code_1702473707471" data-ke-language="bash" data-ke-type="codeblock"><code>GET movie_dynamic/_doc/1?_source_exclude=movieNm</code></pre>
<h2 data-ke-size="size26">delete api</h2>
<p data-ke-size="size16">문서를 삭제할 때 사용한다. result 항목에 "deleted"항목이 반환되며 version 값이 +1 증가한 것을 볼 수 있다.</p>
<pre id="code_1702473673889" data-ke-language="bash" data-ke-type="codeblock"><code>DELETE movie_dynamic/_doc/1</code></pre>

<h2 data-ke-size="size26">Delete By Query api</h2>
<p data-ke-size="size16">특정 인덱스에서 검색을 수행한 후 그 결과에 해당하는 문서만 삭제하고 싶을 경우 사용한다. 이 api를 호출하면 해당 인덱스의 snapshot을 불러와 snapshot이 있는 문서의 버전을 기반으로 삭제를 수행한다.</p>
<pre id="code_1702473642682" data-ke-language="bash" data-ke-type="codeblock"><code>POST movie_dynamic/_delete_by_query
{
	"query": {
		"term": {
			"movieCd": "20173732"
		}
	}
}</code></pre>

<h2 data-ke-size="size26">Update api</h2>
<p data-ke-size="size16">스크립트를 바탕으로 문서를 수정할 수 있다. 스크립트를 통해 "ctx._source.{필드명}"과 같은 형태로 접근할 수 있다. update가 호출되면 엘라스틱서치는 index에서 문서를 가져와 스크립트를 수행한 후 이를 다시 재색인한다. 이러한 동작 원리 때문에 Update api를 사용하기 위해서는 _source필드가 활성화 되어있어야한다. 또한 ctx필드에서는 _source 변수뿐 아니라 추가적인 변수도 사용할 수 있다.</p>
<pre id="code_1702473975040" data-ke-language="bash" data-ke-type="codeblock"><code>POST movie_dynamic/_doc/1/_update
{
	"script" : {
		"source": "ctx._source.counter + params.count",
		"lang": "painless",
		"params" : {
			"count": 1
		}
	}
}</code></pre>

<h2 data-ke-size="size26">Bulk api</h2>
<p data-ke-size="size16">한 번에 다수의 문서를 색인하거나 삭제할 수 있다. 색인 작업의 경우 한 번에 처리함으로써 색인 속도를 크게 향상시킬 수 있다. 여러 건의 데이터가 한 번에 처리되기 때문에 도중에 실패가 발생하더라도 이미 갱신되거나 수정된 결과는 <u><b>원복되지 않는다.</b></u> 아래 예제는 ID가 1, 3인 문서를 추가하고 ID가 2인 문서를 삭제하며 ID가 1인 문서의 속성을 추가한다.</p>
<pre id="code_1702474455171" data-ke-language="bash" data-ke-type="codeblock"><code>POST bulk

{ "index": { "_index": "movie_dynamic", "_type" : "_doc", "_id":"1" } }
{ "title": "살아남은 아이"}

{ "delete": { "_index": "movie_dynamic", "_type" : "_doc", "_id" : "2" } }

{ "index" : { "_index": "movie_dynamic", "_type": "_doc", "_id" : "3" } }
{ "title": "프렌즈: 몬스터섬의비밀" }

{ "update": {"_index": "movie_dynamic", "_type" : "_doc", "_id" : "1",} }
{ "doc":{"movieNmEn": "Last Child"}}</code></pre>

<h2 data-ke-size="size26">Reindex api</h2>
<p data-ke-size="size16">한 인덱스에서 다른 인덱스로 문서를 복사할 때 사용한다. source가 복사할 인덱스이고 dest가 복사될 인덱스이다. 기본적으로 Reindex api는 1,000건 단위로 스크롤을 수행한다. 이때 size 항목을 지정해 스크롤 크기를 변경할 수 있다. 많은 양의 문서를 복사해야한다면 size 값을 늘려서 전체적인 속도 향상을 할 수 있다.</p>
<pre id="code_1702474749077" data-ke-language="bash" data-ke-type="codeblock"><code>POST /_reindex
{
	"source": {
		"index": "movie_dynamic"
	},
	"dest": {
		"index": "movie_dynamic_new"
	}
}

# 특정 조회 결과와 일치하는 문서만 복사
POST _reindex
{
	"source": {
		"index": "movie_dynamic",
		"type": "_doc",
		"query": {
			"term": {
				"title.keyword": "프렌즈: 몬스터섬의비밀"
			}
		}
	},
	"dest": {
		"index": "movie_dynamic_new"
	}
}

# 특정 기준으로 정렬해서 문서 복사
POST _reindex
{
	"size": 10000,
	"source": {
		"index": "movie_dynamic",
		"sort": {
			"counter": "desc"
		}
	},
	"dest": {
		"index": "movie_dynamic_new"
	}
}</code></pre>
            
            
                </div></div>

시뻘건 개발 도전기

인덱스를 활용하기 위해서는 Document api를 사용할 수 있다. 엘라스틱서치에서는 인덱스 관리를 위해 Document api를 제공하는데 이를 이용해 문서를 조회하거나 추가/수정/삭제 등의 작업을 할 수 있다.
 
문서 파라미터
Document api에서는 다양한 파라미터를 지원한다. 이러한 파라미터는 Document api에서 공통적으로 사용할 수 있다.
 
문서 ID 자동생성
문서를 생성할 때는 각 문서를 구분하기 위해 ID가 반드시 필요하다. 만약 문서를 추가할 때 ID를 지정하지 않으면 엘라스틱서치가 자동으로 부여한다. 자동으로 생성되는 ID는 UUID 형태의 값으로 생성된다.
 
버전 관리
색인된 모든 문서는 버전 값을 가지고있다. 버전 정보는 색인할 때 결과에 포함된다. 최초 1을 갖게되고 문서를 변경할 때마다 증가한다. Update api를 이용할 경우 내부적으로 snapshot을 생성해서 문서를 수정하고 인덱스에 다시 재색인하게되는데 이때 버전 정보를 이용한다.
 
오퍼레이션 타입
일반적으로 ID가 이미 존재하는 경우에는 update 작업이 일어나고, ID가 없을 경우에는 create 작업이 일어난다. update 작업이 일어날 때 데이터가 존재할 경우 update하지 않고 색인이 실패하길 원한다면 op_type을 이용할 수 있다. index api를 호출할 때 op_type 파라미터를 이용하면 수행되는 작업의 유형을 강제로 지정할 수 있다. 
PUT movie_dynamic/_doc/1?op_type=create
{
	"movieCd": "20173732",
	"movieNm": "살아남은 아이",
	"movieNmEn": "Last Child",
	"typeNm":"단편"
}
{
	"error": {
		"root_cause": [
			{
				"type": "version_conflict_engine_exception",
				"reason": "[_doc][1]: version conflict, document already exists (current version [1])",
				"index_uuid": "394eLiPOTb6qUI9fftvHfw",
				"shard": "3",
				"index": "movie_dynamic"
			}
		],
			"type": "version_conflict_engine_exception",
            "reason": "[_doc][1]: version conflict, document already exists (current version [1])",
            "index_uuid": "394eLiPOTb6qUI9fftvHfw",
            "shard": "3",
            "index": "movie_dynamic"
	},
	"status": 409
}
 
타임아웃 설정
이미 색인 작업이 진행 중인 동안 추가적으로 색인 api가 호출될 경우에는 일정 기간 대기하게된다. 기본적으로 1분간 대기하게되는데 1분이 지날 경우에는 요청 자체가 실패한다. 이때 timeout 파라미터를 설정해서 대기 시간을 조정할 수 있다.
# 5분간 다른 색인 api가 완료되기를 기다린다.
PUT movie_dynamic/_doc/1?timeout=5m
{
	"movieCd": "20173732",
	"movieNm": "살아남은 아이",
	"movieNmEn": "Last Child",
	"typeNm":"단편"
}
 
인덱스 맵핑 정보 자동 생성
색인할 때 기존에 정의되지 않은 필드의 정보가 존재할 경우 기본적으로는 동적 맵핑을 허용하기 때문에 색인 즉시 새로운 필드가 생성된다. 동적 맵핑을 허용할 경우 원치 않는 오류가 발생할 수 있기 때문에 비활성화를 염두해두어야한다.
action.auto_create_index: 인덱스 자동 생성 여부를 설정한다. 기본 값은 true
index.mapper.dynamic: 동적 맵핑 사용 여부를 설정한다. 기본 값은 true
 
index api
문서를 특정 인덱스에 추가할 때 사용한다. 새로 추가된 문서는 버전 값으로 1이 부여되며 업데이트 될 때마다 +1 증가한다.
 
get api
특정 문서를 인덱스에서 조회할 때 사용한다. 조회하고자 하는 문서의 ID를 명시적으로 지정해서 사용한다. 일반적으로 조회되는 문서의 내용은 _source 항목으로 확인할 수 있다.
GET movie_dynamic/_doc/1?_source_exclude=movieNm
delete api
문서를 삭제할 때 사용한다. result 항목에 "deleted"항목이 반환되며 version 값이 +1 증가한 것을 볼 수 있다.
DELETE movie_dynamic/_doc/1
 
Delete By Query api
특정 인덱스에서 검색을 수행한 후 그 결과에 해당하는 문서만 삭제하고 싶을 경우 사용한다. 이 api를 호출하면 해당 인덱스의 snapshot을 불러와 snapshot이 있는 문서의 버전을 기반으로 삭제를 수행한다.
POST movie_dynamic/_delete_by_query
{
	"query": {
		"term": {
			"movieCd": "20173732"
		}
	}
}
 
Update api
스크립트를 바탕으로 문서를 수정할 수 있다. 스크립트를 통해 "ctx._source.{필드명}"과 같은 형태로 접근할 수 있다. update가 호출되면 엘라스틱서치는 index에서 문서를 가져와 스크립트를 수행한 후 이를 다시 재색인한다. 이러한 동작 원리 때문에 Update api를 사용하기 위해서는 _source필드가 활성화 되어있어야한다. 또한 ctx필드에서는 _source 변수뿐 아니라 추가적인 변수도 사용할 수 있다.
POST movie_dynamic/_doc/1/_update
{
	"script" : {
		"source": "ctx._source.counter + params.count",
		"lang": "painless",
		"params" : {
			"count": 1
		}
	}
}
 
Bulk api
한 번에 다수의 문서를 색인하거나 삭제할 수 있다. 색인 작업의 경우 한 번에 처리함으로써 색인 속도를 크게 향상시킬 수 있다. 여러 건의 데이터가 한 번에 처리되기 때문에 도중에 실패가 발생하더라도 이미 갱신되거나 수정된 결과는 원복되지 않는다. 아래 예제는 ID가 1, 3인 문서를 추가하고 ID가 2인 문서를 삭제하며 ID가 1인 문서의 속성을 추가한다.
POST bulk
{ "index": { "_index": "movie_dynamic", "_type" : "_doc", "_id":"1" } }
{ "title": "살아남은 아이"}
{ "delete": { "_index": "movie_dynamic", "_type" : "_doc", "_id" : "2" } }
{ "index" : { "_index": "movie_dynamic", "_type": "_doc", "_id" : "3" } }
{ "title": "프렌즈: 몬스터섬의비밀" }
{ "update": {"_index": "movie_dynamic", "_type" : "_doc", "_id" : "1",} }
{ "doc":{"movieNmEn": "Last Child"}}
 
Reindex api
한 인덱스에서 다른 인덱스로 문서를 복사할 때 사용한다. source가 복사할 인덱스이고 dest가 복사될 인덱스이다. 기본적으로 Reindex api는 1,000건 단위로 스크롤을 수행한다. 이때 size 항목을 지정해 스크롤 크기를 변경할 수 있다. 많은 양의 문서를 복사해야한다면 size 값을 늘려서 전체적인 속도 향상을 할 수 있다.
POST /_reindex
{
	"source": {
		"index": "movie_dynamic"
	},
	"dest": {
		"index": "movie_dynamic_new"
	}
}
# 특정 조회 결과와 일치하는 문서만 복사
POST _reindex
{
	"source": {
		"index": "movie_dynamic",
		"type": "_doc",
		"query": {
			"term": {
				"title.keyword": "프렌즈: 몬스터섬의비밀"
			}
		}
	},
	"dest": {
		"index": "movie_dynamic_new"
	}
}
# 특정 기준으로 정렬해서 문서 복사
POST _reindex
{
	"size": 10000,
	"source": {
		"index": "movie_dynamic",
		"sort": {
			"counter": "desc"
		}
	},
	"dest": {
		"index": "movie_dynamic_new"
	}
}

Document API 이해하기

댓글