Update API는 제공된 script에 따라 document를 업데이트한다. Operation은 index로부터 document를 조회하고 script를 실행하여 그 결과를 index에 저장한다. 물론 조회나 reindex하는 과정에서 업데이트가 없다는 것은 버전으로 확인할 수 있다.

이 operation은 document의 full reindex를 의미하며, network roundtrip을 제거하고 get operation과 index사이에 버전 변경으로 인한 충돌을 감소시켜야 함에 유의하라. 이러한 특징을 해결하기 위해서 _source field가 필요하다.

예를 들어 다음 간단한 document를 index해보자.

curl -XPUT localhost:9200/test/type1/1 -d '{
   "counter" : 1,
   "tags" : ["red"]
}'

이제 counter를 증가시키는 script를 실행할 수 있다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "script" : "ctx._source.counter += count",
   "params" : {
       "count" : 4
   }
}'

또한 태그 리스트에 태그를 추가할 수도 있다. (만약 태그가 존재하더라도 리스트이기 때문에 추가된다.)

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "script" : "ctx._source.tags += tag",
   "params" : {
       "tag" : "blue"
   }
}'

Document에 새로운 field도 추가할 수 있다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "script" : "ctx._source.name_of_new_field = \"value_of_new_field\""
}'

Document로부터 field를 삭제할 수도 있다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "script" : "ctx._source.remove(\"name_of_field\")"
}'

태그가 blue인 document를 삭제하거나, blue가 아닐 경우 삭제하지 않을 수도 있다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "script" : "ctx._source.tags.contains(tag) ? ctx.op = \"delete\" : ctx.op = \"none\"",
   "params" : {
       "tag" : "blue"
   }
}'

[NOTE]

3진 operator와 assignment를 다루는 것을 알아야 한다. Assignment operation은 3진 operator에 비해서 우선순위가 낮다. 다음 항목들을 비교해 보자.

// Will NOT update the tags array
ctx._source.tags.contains(tag) ? ctx.op = \"none\" : ctx._source.tags += tag
// Will update
ctx._source.tags.contains(tag) ? (ctx.op = \"none\") : ctx._source.tags += tag
// Also works
if (ctx._source.tags.contains(tag)) { ctx.op = \"none\" } else { ctx._source.tags += tag }

Update API를 통해서 또한 document의 일부분만 전송할 수 있다. 전송된 내용은 이미 존재하는 document에 merge된다. (간단히 말하자면 recursive merge, object의 inner merge, "key/value" array를 replace하는 것이다.)

예를 들면 다음과 같다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "doc" : {
       "name" : "new_name"
   }
}'

Doc과 script를 지정하면 doc은 무시된다. Script내에 document의 일부분에 해당하는 field pair를 넣는 것이 가장 좋다. 기본적으로 doc이 지정되면, document는 merge process가 어떤 변화를 일으키지 않더라도 항상 update된다. Detect_noop을 true로 설정하면 Elasticsearch에서 변경사항이 있는지를 체크하고 아니면 update request가 noop이 된다. 예를 들면 다음과 같다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "doc" : {
       "name" : "new_name"
   },
   "detect_noop": true
}'

Request가 보내지기 전에 name이 new_name이라면 전체 update request는 무시한다.

Upserts

Elasticsearch Update API에는 upsert도 있다. Document가 이미 존재하지 않으면, upsert element의 content는 새로운 document로 index될 것이다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "script" : "ctx._source.counter += count",
   "params" : {
       "count" : 4
   },
   "upsert" : {
       "counter" : 1
   }
}'

Document가 없으면 스크립트를 통해서 client에는 알려지지 않은 business logic을 사용하여 document content를 초기화하도록 할 수 있다. 이런 경우에는 새로운 scripted_upsert parameter를 true로 설정하면 된다.

curl -XPOST 'localhost:9200/sessions/session/dh3sgudg8gsrgl/_update' -d '{
   "script_id" : "my_web_session_summariser",
   "scripted_upsert":true,
   "params" : {
       "pageViewEvent" : {
               "url":"foo.com/bar",
               "response":404,
               "time":"2014-01-01 12:32"
       }
   },
   "upsert" : {
   }
}'

Default scripted_upsert 설정은 false이다. 이것은 script가 insert를 위해서는 실행되지 않음을 의미한다. 그러나 위와 같은 시나리오에서처럼 새로운 "indexed scripts" feature를 이용하여 저장된 중요한 (non-trivial) script를 사용할 수 있다. 스크립트를 통해서 여러 page view event에 기반한 web session의 기간 (duration)과 같은 특징들을 뽑아낼 수도 있다. Client에서는 blank "upsert" document를 제공하거나 params element로 넘겨진 event를 사용하여 최대한 상세하게 채워서 script를 실행할 수도 있다.

마지막으로 upsert 기능은 doc_as_upsert도 지원한다. 제공된 document는 기존에 존재하지 않는 document일 경우에 insert된다. 이것은 Elasticsearch로 전송되는 데이터의 양을 감소시킬 것이다.

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
   "doc" : {
       "name" : "new_name"
   },
   "doc_as_upsert" : true
}'

Parameters

Update operation은 index API처럼 유사한 parameter를 지원한다.

Routing : document를 적합한 shard로 route하는데 사용하는 설정

Parent : routing의 단순 설정

Timeout : shard가 다시 사용가능해질 때까지 기다리는 시간

Replication : delete/index operation (sync, async)에 대한 replication type. 1.5.0에서 deprecated.

Consistency : index/delete operation의 write consistency

Refresh : 전체 index가 아니라 적합한 primary와 replica shard를 operation이 발생한 이후 즉시 refresh. 따라서, update document가 바로 검색 결과로 나타난다.

Fields : update된 document로부터 적합한 fields를 리턴. 전체 update된 source를 리턴하기 위해서 _source를 지원.

Version & version_type : Update API는 Elasticsearch 내부에서 지원하는 versioning을 사용함. Update되는 동안 document가 변경되지 않았음을 version으로 판별. 특정 version의 document를 update하기 위해서 version parameter를 사용할 수도 있음. Version type을 force로 설정하면 강제로 document를 update하고 새로운 version이 부여됨. (사용하는데 주의할 것! Force를 사용하면 document가 변경되지 않았음을 보증할 수 없음.) external & external_gte version type은 지원되지 않음

조회한 document와 그것을 indexing / deleting하는 사이에 version 충돌이 발생하면 몇번이나 retry해야 하는지를 설정하는 Retry_on_conflict 를 지원한다. Default는 0이다.

또한 ctx._ttl을 사용하여 document의 ttl을 update할 수 있다. 그리고 ctx._timestamp를 사용하여 document의 timestamp를 update할 수 있다. 만약 timestamp가 update되지 않았고, _source로부터 추출된다면 update date를 설정할 것이다.

_source에 추가로 다음과 같은 variable들을 ctx map에 이용할 수 있다. : _index, _type, _id, _version, _routing, _parent, _timestamp, _ttl

Delete API는 id를 가지고 특정 index에서 JSON document를 삭제한다. 다음 예제는 twitter index, tweet type, id 값이 1인 JSON document를 삭제하는 것을 보여준다.

$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1'

위 delete operation의 결과는 다음과 같다.

{
   "found" : true,
   "_index" : "twitter",
   "_type" : "tweet",
   "_id" : "1",
   "_version" : 2
}

Versioning

Index된 각 document는 version이 붙여진다. Document를 삭제할 때, version은 지우려고 하는 document가 실제로 지우려고 하는 것으로 적절한지 삭제하는 동안 변경되지 않는지 확신할 수 있게 한다. Delete를 포함하여 Document에  write operation이 매번 실행될 때마다 버전이 증가한다.

Routing

Routing을 제어하기 위해 indexing을 사용할 때, document를 삭제하기 위해서 routing value가 제공되어야만 한다. 예를 들면 다음과 같다.

$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1?routing=kimchy'

위의 결과는 id 1인 document를 삭제할 것이다. 하지만 사용자 기반으로 route될 것이다. 정확한 route없이 삭제하는 경우 document가 삭제되지 않을 수도 있다.

많은 경우에 routing value는 document를 삭제할 때 주어지지 않는다. 그러한 경우에서는 _routing이 required로 맵핑되었지만 routing이 없으면 전체 shard에 있는 값들을 자동으로 삭제할 것이다.

Parent

Parent parameter가 설정되면, routing parameter가 설정되는 것과 기본적으로 동일하다. Parent document를 삭제하는 것은 그 자식까지 자동으로 삭제하지는 않음에 유의하라. 주어진 id에 해당하는 parent의 모든 자식 document를 삭제하는 한가지 방법은 자동으로 생성되고 index된 field _parent로 child index를 삭제하는 쿼리 (https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html) 를 수행하는 것이다. 형식은 parent_type#parent_id이다.

Automatic index creation

Delete operation은 이전에 생성되지 않았으면 자동으로 index를 생성한다. (수동으로 index를 생성하는 index API를 확인하라). 그리고 이전에 생성되지 않았다면, 자동으로 특정 type에 대해 맵핑되는 type을 동적으로 생성한다. (mapping type을 수동으로 생성하는 put mapping AP?I에 대해서 확인하라.)

Distributed

Delete operation은 hash값으로 해당 shard id를 얻는다. 그리고 그 id group내의 primary shard로 redirect 되고, id group에 속한 shard replica로 (필요하다면) 복제된다.

Replication Type

[WARNING]

1.5.0에서 deprecated됨.

Async replication을 지정하는 것은 deprecate되었고, 버전 2.0.0에서는 삭제될 것이다.

Operation 복제 (replication)는 async 방식으로 replica로 처리될 수 있다. (operation은 primary shard에 수행되고 리턴될 것이다.) replication parameter는 async로 설정될 수 있다. (기본값은 sync이다.)

Write Consistency

Partition 내 (replication group) 에서 Operation이 active shard 수에 근거하여 실행되도록 허용된다면 통제하라. 그 값은 one, quorum, all이 있다. Consistency parameter는 node level 설정에서 기본적으로 action.write_consistency가 quorum으로 설정되어 있다.

예를 들면, 2개의 replica index를 가지는 N개의 shard가 있다면, operation이 성공하기 위해서는 적합한 partition (quorum)내에 최소한 2개의 active shard가 있어야만 할 것이다. 1개의 replica를 가지는 N개의 shard가 있는 시나리오에서는 하나의 shard active가 있어야 한다. (이 경우에는 one 과 quorum이 같다.)

Refresh

Refresh parameter는 적합한 primary를 refresh하고 delete operation이 일어난 이후 replica shard를 통해 검색할 수 있도록 true로 설정될 수 있다. True로 설정하는 것은 시스템에 과부하를 주지 않을 것이라는 주의 깊은 생각과 확신 하에 이루어져야 한다. (indexing하는데 느려질 수도 있다.)

Timeout

Delete operation을 수행하도록 할당된 primary shard는 delete operation이 수행되는 동안에는 이용할 수 없다. 몇가지 이유로 primary shard는 gateway로부터 즉시 복구되거나 재배치를 겪는다. 기본적으로 delete operation은 primary shard가 이용가능해질 때까지 1분을 기다릴 것이다. 그 이후에는 요청이 실패하고 error로 응답한다. Timeout parameter는 얼마나 오래 기다릴지 명시적으로 지정하는데 사용할 수 있다. 다음 예제에서는 timeout값을 5분으로 설정했다.

$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1?timeout=5m'