环境
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