Index API

Index API 用于在指定索引中添加或更新类型化的JSON文档，使其成为可搜索的。 如下示例将JSON文档插入“twitter”索引中，类型名为“_doc”，ID为1：

PUT twitter/_doc/1
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

返回结果以下：

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

_shards头提供关于索引操做的复制过程的信息。

• total - 表示执行索引操做的分片副本(主和副本分片)的数量。
• successful - 表示索引操做成功的分片数量。
• failed - 在副本分片上的索引操做失败的状况下，包含复制相关错误的数组。

在successful至少为1的状况下，索引操做才会成功。

当索引操做成功返回时（默认状况下，只须要主分片，但能够更改此行为），副本分片可能不会都启动。 在这种状况下，总数将等于number_of_replicas设置的总分片数，成功数将等于启动的分片数（primary + replicas）。 若是没有失败，失败将为0。

自动建立索引

若是以前没有建立索引，索引操做会自动建立一个索引（查看create index API 了解如何手动建立索引）。还会为指定类型自动建立（查看put mapping API了解如何手动建立类型映射）一个动态类型映射（若是还没有建立的话）。

映射自己很是灵活而且无模式（schema-free）。新的字段和对象将自动添加到指定类型的映射定义中。查看映射部分以获取更多关于映射定义的信息。
自动索引建立能够经过在全部节点的配置文件中设置 action.auto_create_index=false 来禁用。设置 index.mapper.dynamic=false能够禁用自动建立映射。

自动索引建立能够包括基于模式的白/黑名单，例如，设置  action.auto_create_index 为+aaa*， -bbb*，+ccc*，-*（+表示容许，- 意为不容许）。

版本控制

每一个索引文档都有一个版本号。 关联的版本号做为响应的一部分返回。 当指定版本参数时，索引API能够选择性地容许进行乐观并发控制。 这就能够控制将要执行的操做的文档版本。版本控制一个很好的例子就是执行事务（读取而后更新）。 指定最初读取的文档中的版本可确保在此期间未发生任何更改（若是读取是为了更新，建议在查询时设置preference=_primary）。 例如：

PUT twitter/_doc/1?version=2
{
    "message" : "elasticsearch now has versioning support, double cool!"
}

GET twitter/_doc/1?preference=_primary

注意：版本控制是彻底实时的，而且不受搜索操做的近实时方面的影响。若是没有提供版本，则操做在没有任何版本检查的状况下执行。

默认状况下，使用内部版本控制，从1开始，每次增长或删除就加1。版本号也能够用外部值补充（例如保存在数据库中）。要启用此功能，应设置 version_type=external 。提供的值必须是numeric, long类型的，且值必须是大于或等于0且小于大约9.2e + 18的。在使用外部版本类型时，系统会检查传递给索引请求的版本号是否大于当前存储的文档的版本号，而不是检查是否匹配版本号。若是为true，则文档将被索引并使用新版本号。若是提供的值小于或等于存储文档的版本号，则会发生版本冲突，索引操做将失败。

外部版本控制支持将值0做为有效的版本号。 这容许版本与外部版本控制系统同步（好比版本号从0开始而不是1的系统）。坏处是版本号等于零的文档不能使用Update-By-Query API更新，也不能使用Delete By Query API进行删除。

好处是只要使用源数据库的版本号，就不须要因源数据库更改而执行的异步索引操做进行严格排序。 若是使用外部版本控制，即便是使用数据库中的数据更新Elasticsearch索引也会获得简化，由于若是索引操做出现故障，则只会使用最新版本。

版本类型

上面已经解释了internal & external 版本类型，Elasticsearch还支持针对特定用例的其余类型。如下是不一样版本类型及其语义的概述。
internal：若是给定版本与存储文档的版本相同，则索引文档。
external or external_gt：若是给定版本严格高于存储文档的版本或者文档不存在，则索引文档。 给定的版本将用做新版本，并将与新文档一块儿存储。 提供的版本必须是非负数长整数。
external_gte：若是给定版本等于或高于存储文档的版本，则索引文档。 若是文档不存在，操做也会成功。 给定的版本将用做新版本，并将与新文档一块儿存储。 提供的版本必须是非负数长整数。
注：external_gte版本类型只适用于特殊用途，应谨慎使用。 若是使用不当，可能会致使数据丢失。 还有另外一个选项force，因为它可能致使主分片和副本分片不一致，所以不推荐使用。

操做类型

索引操做还接受可用于强制执行建立操做的op_type，从而容许“若是不存在就添加”行为。 使用create时，若是索引中已存在由该id建立的文档，则索引操做将失败。

如下是使用op_type参数的示例：

PUT twitter/_doc/1?op_type=create
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

也能够像下面这样指定create：

PUT twitter/_doc/1/_create
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

自动生成ID

索引操做能够在不指定id的状况下执行。 它会自动生成一个id。 另外，op_type会自动设置为create。 如下是一个例子（注意使用POST而不是PUT）：

POST twitter/_doc/
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

结果以下：

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

路由

默认状况下，分片放置或路由经过文档的id值的hash进行控制。 为了更明确的控制，路由使用的哈希函数中引入的值可使用路由参数直接指定。 例如：

POST twitter/_doc?routing=kimchy
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

在上面的示例中，“_doc”文档根据提供的路由参数：“kimchy” 被路由到一个分片。

设置显式映射时，能够选择使用_routing字段来指示索引操做从文档自己提取路由值。 这会额外增长文档解析开销，不过成本很是小。 若是_routing映射被定义并被设置为必需的，那么若是路由值未提供或未提取到路由值，则索引操做将失败。

分步式

索引操做根据其路由（参见上面的路由部分）指向主分片，并在包含此分片的实际节点上执行。 在主分片完成操做后，若是须要，更新将分发到相应的副本。

等待活动分片

为了提升写入系统的灵活性，索引操做能够配置为在继续操做以前等待必定数量的活动分片副本。 若是所需数量的活动分片副本不可用，则写入操做必须等待并重试，直到必要的分片副本已启动或发生超时。 默认状况下，写入操做仅等待主分片在进行以前处于活动状态（即wait_for_active_shards = 1）。 经过设置index.write.wait_for_active_shards，能够在索引设置中动态覆盖此默认值。 要改变每一个操做的这种行为，可使用wait_for_active_shards请求参数。

有效值为所有或任何正整数，直到索引中每一个分片的配置副本总数（即number_of_replicas + 1）。指定负值或大于分片数量的数字将引起错误。

例如，假设咱们有一个由三个节点A，B和C组成的集群，而且咱们建立了一个索引index，其副本数设置为3（致使4个分片副本，比节点多一个副本）。若是咱们尝试进行索引操做：
一、默认状况下，操做只会确保每一个分片的主分片可用，而后才能继续。这意味着，即便B和C发生故障，而且A托管了主分片副本，索引操做仍然会继续执行这惟一的一个数据副本。
二、若是请求中的wait_for_active_shards设置为3（而且全部3个节点都在运行），那么索引操做在继续以前须要3个活动分片副本，知足要求，由于集群中有3个活动节点，每一个节点持有分片的副本。
三、若是咱们将wait_for_active_shards设置为all（或者4也同样），则索引操做将不会继续，由于咱们没有在索引中激活每一个分片的全部4个副本。该操做将超时，除非在集群中引入新节点来托管分片的第四个副本。
值得注意的是，这种设置大大下降了写操做不写入所需数量的分片副本的可能性，但它并不能彻底消除这种可能性，由于在写操做开始以前就会发生这种检查。 一旦写入操做正在进行，复制仍然有可能在任意数量的分片副本上失败，但仍然能够在主分片上成功。 写操做响应的_shards部分会显示复制成功/失败的分片副本的数量。

{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    }
}

刷新

控制此请求所作的更改对搜索是否可见。 请参阅刷新。

Noop Updates

使用索引api更新文档时，即便文档未更改，也始终建立新版本的文档。 若是不想这样，可使用_update api，把detect_noop设置为true。 这个选项在索引api上不可用，由于索引api没有获取旧的数据，也没法将它与新的数据进行比较。

关于Noop Updates什么时候不可接受，并无一条硬性规定。 这是多种因素的结合，例如数据源发送更新的频率其实是noops，以及Elasticsearch每秒接收更新时在分片上运行的查询数量。

Timeout

执行索引操做时，分配用于执行索引操做的主分片可能不可用。 形成这种状况的一些缘由多是主分片正在从网关恢复或正在进行迁移。 默认状况下，索引操做将在主分片上等待最多1分钟，而后若是失败则响应并显示错误。 timeout参数可用于显式指定它等待的时间。 如下是将其设置为5分钟的示例：

PUT twitter/_doc/1?timeout=5m
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

官方文档：https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html