elasticsearch之Document APIs【Update API】

环境

elasticsearch：5.5

Update API

update API 允许提供一个脚本来更新文档，该操作会从相应的索引（即数据库）中获得文档（具体点：从相应的分片中获取）。运行脚本（脚本语言和参数是可选的），并且返回索引结果（也允许删除或者忽视该操作）。使用版本号来确保在get和reindex期间没有更新发生。

注意，这个操作仍然意味着文档需要完整的重新索引，it just removes some network roundtrips和减少查询和插入之间的版本号冲突的几率。需要启用_source字段来使这种特性生效。

例如，插入一个简单文档：

PUT test/type1/1{    "counter" : 1,    "tags" : ["red"]}

Scripted updates

现在，我们执行一个脚本来增加counter字段：

POST test/type1/1/_update{    "script" : {        "inline": "ctx._source.counter += params.count",        "lang": "painless",        "params" : {            "count" : 4        }    }}

我们添加一个tag到tags列表中（注意，如果tag存在，它将会被添加，因为它是个列表）：

POST test/type1/1/_update{    "script" : {        "inline": "ctx._source.tags.add(params.tag)",        "lang": "painless",        "params" : {            "tag" : "blue"        }    }}

除了_source，下面变量可以通过ctx map来获得：_index, _type, _id, _version, _routing, _parent, 和_now(当前时间戳)。

我们也可以添加一个字段到文档中：

POST test/type1/1/_update{    "script" : "ctx._source.new_field = 'value_of_new_field'"}

或者从文档中移除一个字段：

POST test/type1/1/_update{    "script" : "ctx._source.remove('new_field')"}

并且，我们甚至可以改变执行的操作。下面这个例子是如果tags字段包含green,就删除文档，否则就什么都不做：

POST test/type1/1/_update{    "script" : {        "inline": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'none' }",        "lang": "painless",        "params" : {            "tag" : "green"        }    }}

Updates with a partial document(更新部分文档）

update API 也支持传递部分文档，其将会被合并到已存在的文档（简单递归合并，内部合并对象，替换核心键值对keys/values和数组）。例如：

POST test/type1/1/_update{    "doc" : {        "name" : "new_name"    }}

如果doc和script都指定，那么doc会被忽视掉。最好是将部分文档的字段对放在脚本本身中。

Detecting noop updates

如果doc指定了其值，其值将会被合并到已存在的_source中。默认情况下，没有变化的更新会被忽略掉，并且返回"result": "noop"，如下：

POST test/type1/1/_update{    "doc" : {        "name" : "new_name"    }}

如果在发送请求之前，name字段已经是new_name啦，接着整个更新请求都会被忽略。
如果请求已经忽略了，那么在返回的响应result元素中，其值为noop:

{   "_shards": {        "total": 0,        "successful": 0,        "failed": 0   },   "_index": "test",   "_type": "type1",   "_id": "1",   "_version": 6,   "result": noop}

你也可以禁用这种行为，将detect_noop设置为false：

POST test/type1/1/_update{    "doc" : {        "name" : "new_name"    },    "detect_noop": false}

Upserts

如果文档不存在，那么upsert元素的内容将会作为新文档插入进行。如果文档已经存在，接着script将会被执行：

POST test/type1/1/_update{    "script" : {        "inline": "ctx._source.counter += params.count",        "lang": "painless",        "params" : {            "count" : 4        }    },    "upsert" : {        "counter" : 1    }}

scripted_upsert

如果你希望运行脚本，而不管文档是否存在——即用脚本来初始化文档而不是upsert元素——设置scripted_upsert为true：

POST sessions/session/dh3sgudg8gsrgl/_update{    "scripted_upsert":true,    "script" : {        "id": "my_web_session_summariser",        "params" : {            "pageViewEvent" : {                "url":"foo.com/bar",                "response":404,                "time":"2014-01-01 12:32"            }        }    },    "upsert" : {}}

doc_as_upsert

设置doc_as_upsert为true，使用doc的内容作为upsert的值，而不是发送一部分doc加upsert doc：

POST test/type1/1/_update{    "doc" : {        "name" : "new_name"    },    "doc_as_upsert" : true}

参数：

更新操作支持以下查询字符串参数：

参数名 描述 retry_on_conflict 在查询和插入阶段更新时，很有可能其他进程在此之前更新同一个文档。默认情况下，此处更新将会失败并且会抛出版本冲突异常。retry_on_conflict参数控制在最终抛出异常之前，重试更新多少次 routing 如果更新的文档不存在，那么就会根据routing将更新请求路由到正确的分片上并且将routing设置给upsert请求。已存在的文档不能更新路由（routing） parent 如果更新的文档不存在，那么就会根据parent将更新请求路由到正确的分片上并且将parent设置给upsert请求。已存在的文档不能更新parent。如果给索引（数据库）路由指定了别名，那么该别名会覆盖parent路由，并且会被用于路由请求。 timeout 分片变为可利用之前的等待超时时间 wait_for_active_shards 在处理更新请求操作之前，副本分片必须存活的数量。详情参考这里 refresh 控制此处请求做出的更改对于搜索而已是可见的。参考?refresh _source 在响应中控制是否和如何控制更新返回的source字段。默认情况下，更新的source是不返回的。详情查看source filtering version&version_type update api使用elasticsearch内部版本号，来确保在更新期间，文档没有变化。你也可以使用version参数来指定版本号，只有和指定版本号匹配的情况下才会更新。通过将version type设置为force，你可以在更新文档后，强制新版本号（使用时非常小心，使用force不能确保文档没有发生变化，通俗点就是会忽略版本冲突）。

The update API does not support external versioning

update api 是不支持外部版本号（version types external & external_gte）的，因为它会造成elasticsearch版本号和外部系统不一致。可以使用index api进行替换。

---

参考地址：
https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update.html