elasticsearch 6.x (五) 单一文档 API 介绍和使用 update和delete API

大家好，我是烤鸭：

    今天分享的是官网6.x    单一文档(Single document APIs)APIs。

    本文这是部分翻译，如果想看全部的，还是建议阅读官方api。链接：

     https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html

1.    删除   (delete) API

删除API允许根据特定的索引从特定的索引中删除类型化的JSON文档。下面的示例从称为twitter的索引，类型是_doc,id是1来删除JSON文档。

    

DELETE /twitter/_doc/1

结果：

{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    },
    "_index" : "twitter",
    "_type" : "_doc",
    "_id" : "1",
    "_version" : 2,
    "_primary_term": 1,
    "_seq_no": 5,
    "result": "deleted"
}

版本控制

索引的每个文档都是版本控制的。删除文档时，可以指定version ，以确保我们试图删除的相关文档实际上已经被删除了，并且同时没有被更改。在文档上执行的每一个写入操作（包括删除操作）都会导致其版本增加。删除文档的版本号在删除后的短时间内仍然可用，以允许对并发操作的控制。删除文档的版本可用的时间由index.gc_deletes参数决定和默认为60秒。

路由

当使用索引控制路由时，删除文档还应提供路由值。例如：

DELETE /twitter/_doc/1?routing=kimchy

以上将删除带有索引为tweet ，id为1的文档，但将基于用户路由。注意，没有正确路由的删除将不会删除成功。
当_routing 映射设置为required ，并且没有指定路由值时，删除API将引发一个路由RoutingMissingException 并拒绝该请求。

自动索引创建

如果使用 external versioning variant，如果索引尚未创建，则删除操作将自动创建一个索引（请检查create indexAPI以手动创建索引），并且如果尚未创建特定类型之前（检查put mappingAPI以手动创建类型映射)，则自动创建动态类型映射。

分布式

删除操作被hash成特定的碎片id。然后，它被重定向到id组内的主碎片中，并在id组内复制（如果需要的话）到碎片副本。

等待active碎片

在执行删除请求时，可以在开始处理删除请求之前设置wait_for_active_shards 参数，以要求最小数量的碎片副本是active的。请参阅这里的详细信息和使用示例。

超时

当主碎片被要求执行删除操作，当操作被执行后，主碎片可能不可用。一些原因可能是，主要碎片目前正在从内存恢复或进行重新定位。默认情况下，删除操作在主碎片在故障和响应错误之前，将等待1分钟。timeout 参数可用于显式指定它等待多长时间。下面是将其设置为5分钟的示例：

DELETE /twitter/_doc/1?timeout=5m

2.    更新   (update) API

更新API允许根据提供的脚本更新文档。从索引获取（与碎片搭配的）文档，运行脚本（带有可选的脚本语言和参数），并返回结果（也允许删除或忽略操作）。它使用版本控制来确保在“获取”和“重新索引”期间没有发生任何更新。
注意，此操作仍然意味着文档的完全重新索引，它只删除一些网络往返行程，降低了获取操作和索引操作之间的版本冲突的可能性。必须启用_source字段来启用此功能。

简单例子：

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

脚本更新

运行脚本，自增计数。

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"
        }
    }
}

除了_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')"
}

而且，我们甚至可以改变执行的操作。如果tags字段包含green，删除文档，否则它不做任何操作（noop）：

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"
        }
    }
}

更新部分文档

更新API还支持传递部分文档，该文档将被合并到现有文档中（简单递归合并、对象内部合并、替换核心“键值对”和数组）。要完全替换现有文档，应该使用index API。下面的部分更新是对现有文档添加了新字段：

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

如果指定了doc 和script ，则忽略doc 。最好是将你的字段对的部分文档放在脚本本身中。

NOOP更新检查

如果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": 6,
   "result": "noop"
}

可以禁用上面的更新检查：

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

更新插入

如果文档不存在，则upsert 元素的内容将作为新文档插入。如果文档确实存在，那么script 将被执行：

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

更新插入脚本

如果不管文档是否存在，脚本都运行的话，即脚本代替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 加上upsert doc ，将doc_as_upsert 设置为true 将使用doc 的内容作为upsert 值：

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

参数

更新操作支持下列query-string 参数：

retry_on_conflict 

在更新的获取和索引阶段之间，可能另一个进程可能已经更新了同一文档。默认情况下，更新操作将因版本冲突异常而失败。retry_on_conflict 参数控制在最终抛出异常之前重试更新的次数。

routing

路由用于将指引更新请求路由到正确的碎片，如果更新的文档不存在，则为更新插入请求设置路由。不能用于更新已存在文档的路由。

timeout

碎片的超时等待变成可用。

wait_for_active_shards

在进行更新操作之前需要active的碎片副本的数量。详情请见这里。

refresh

控制此请求所做的更改为可见的并且能够搜索到。详情见这里。

_source

控制被更新的source是否可以以及如何在响应中返回。默认情况下，更新的source不返回。有关详细信息，请参见source filtering 。

version

Update API在内部使用依靠es的版本控制支持，以确保文档在更新过程中不会改变。可以使用version 参数指定文档仅在其版本与指定的版本匹配时才被更新。

更新API不支持除内部版本之外的版本控制。

更新API不支持外部（版本类型external 和external_gte）或强制（版本类型force）版本，因为这会导致es版本号与外部系统不同步。外部请使用使用index API 。

更多关于elasticsearch 6.x内容：

   1.   elasticsearch 6.x 部署 windows入门(一) spingboot连接

    2.   elasticsearch 6.x linux部署(二) kibana x-pack 安装

    3.   elasticsearch 6.x (三) linux 集群多节点部署

     4.   elasticsearch 6.x (四) 单一文档 API 介绍和使用 index和get API