elasticsearch6.7 05. Document APIs（6）UPDATE API

5、 UPDATE API

更新操作可以使用脚本来更新。更新的时候会先从索引中获取文档数据（在每个分片中的集合），然后运行脚本（使用可选的脚本语言和参数），再果进行索引（还允许删除或忽略该操作）。它使用版本号保证在读取文档和重新索引期间，被更新的文档不会发生任何修改操作。

注意，update操作会重新索引文档，它可以减少网络往返次数和降低在获取文档和索引文档之间发生版本号冲突的可能。要支持这一特性，需要开启_source字段（因为要读取旧数据，和替换操作不一样，替换操作不需要读旧数据）.

例如，让我们索引一个简单的文档：

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

5.1 使用脚本更新(Scripted updates)

增加counter字段的值：

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

tags字段增加一个元素：

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

除了_source,下面的变量是可用下面的字段都可以在ctx使用：_index, _type, _id, _version, _routing, _parent, and _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"
        }
    }
}

5.1 脚本更新(Scripted updates)

现在执行一个增加计数器的脚本：

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

下例表示在标签列表中添加一个标签（如果标签存在，它仍会被添加，因为这是一个列表）：

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

可以从标签列表中删除标签。请注意，painless 的 remove 函数是需要你删除的 tag 的 index，因此需要使用更多的逻辑来获取它以避免运行时出错。请注意，如果要删除的 tag 在 tags 里面出现多次，但是只会删除一次。：

POST test/_doc/1/_update
{
    "script" : {
        "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
        "lang": "painless",
        "params" : {
            "tag" : "blue"
        }
    }
}

除了_source之外，ctx 的这些值也可以用：_index，_type，_id，_version，_routing和_now（当前时间戳）。

我们也可以这样添加一个字段：

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

或是这样删除一个字段：

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

我们甚至可以指定 ctx 的操作，如下判断 tags 是否包含 green，如果包含则删除文档，否则不进行任何操作：

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

5.2 局部更新文档（Updates with a partial document）

update API 也支持将部分文档合并到现有文档中（简单的递归合并，对象的属性合并、替换属性值和数组）。要完全替换现有的文档，应使用 index API。以下的部分更新将向现有文档中添加新的字段：

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

如果doc和script一起指定，doc将会被忽略。最好的更新方式是将部分文档的字段对放在脚本本身中。

5.3 检查空操作（Detecting noop updates）

如果指定了doc，则其值将与现有的_source合并。默认情况下，不进行任何内容更改的更新操作会检测到它们不更改任何内容并返回"result": "noop"如下：

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

如果name的值在更新前本来就是new_name,那么这个操作将会被忽略。返回结果的result字段将会是noop：

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

你可以通过设置 detect_noop 为false来禁止 noop，如：

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

5.4 Upserts

如果文档不存在，就创建一个 与upsert字段内容一致的文档，如果文档存在就执行script中的更新操作：

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

5.4.1 scripted_upsert

如果你想不管文档存不存在都要执行script（即，用script来初始化文档而不是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" : {}
}

5.4.2 doc_as_upsert

将doc_as_upsert设置为true，将会把 doc 中的值按照upsert执行：

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

5.5 参数（Parameters）

update操作支持如下查询参数：

• retry_on_conflict
  • 在更新的get和indexing阶段之间，另一个进程可能已经更新了同一文档。默认情况下，更新会因版本冲突而失败。retry_on_conflict参数指定更新失败时重试多少次
• routing
  • routing参数用于将更新请求路由到正确的分片。如果索引的时候指定了该参数，更新的时候也要指定同样的值。在使用upsert字段时，如果文档不存在的时候，就会创建新文档，此时可以指定这个文档的路由值。不能更新一个已存在的文档的routing(就是说不能把文档从一个分片移动到另一个分片)。
• timeout
  • 等待分片变成可用状态的最大时间
• wait_for_active_shards
  • 在执行更新操作前，至少有多少个可用的分片才能执行更新操作。详细请查阅
• refresh
  • 控制此请求所做的更改何时对搜索可见。请查阅refresh
• _source
  • 控制是否以及如何响应更新后的文档，默认不是会返回已更新的_source字段。查阅soruce filtering
• version
  • update API 使用 Elasticsearch 内部版本控制，以确保在更新期间文档不会被其他进程更新。你可以使用version参数指定仅在version和文档版本号一致时才更新文档。（在6.7.0中version以被弃用。请改用if_seq_no和if_primary_term，有关更多详细信息，请参阅乐观并发控制。）

update API不支持内部版本以外的版本控制

update API 不支持外部（external 和 external_gte 版本类型）或强制（force 版本类型）版本控制，这会导致 Elasticsearch 版本号与外部系统不同步。(比如外部版本号可以为0，但是内部版本号不可以为0)。你可以使用indexAPI 代替这个操作。

• if_seq_no 和 if_primary_term
  • 更新操作可以是有条件的，只有在为文档的最后一次修改分配了if_seq_no和if_primary_term参数指定的序列号和主要术语时才能执行。如果检测到不匹配，则操作将导致VersionConflictException和状态代码409.有关详细信息，请参阅乐观并发控制。