环境

虚拟机：centos7
操作系统：win7
elasticsearch：5.4.3

Index API

Index API 是添加或更新在指定索引中添加或者更新json类型的文档。
下面的例子是插入json文档，到索引名（数据库）为：twitter、类型（表名）：tweet、id为：1

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

索引操作结果如下：

{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    },
    "_index" : "twitter",
    "_type" : "tweet",
    "_id" : "1",
    "_version" : 1,
    "created" : true,
    "result" : created
}

_shards标头，提供了关于副本处理索引操作的信息：
①total：表示有多少个分片副本（主分片和副本分片）应该执行索引操作。
②successful：表示成功执行索引操作的分片副本数量
③failed ：表示在副本分片上索引操作失败，包含副本有关的错误信息的数组。

在成功的情况下，successful至少为1。

在索引操作成功返回时，副本分片可以没有全部启动（默认情况下，只要求主分片不是必须（启动），但是这种行为可以被改变）。在这种情况下，total将等于number_of_replicas设置的总的分片数量，successful将等于分片启动的数量（主分片和副本分片）。如果没有失败，failed将等于0。

创建自动索引（Automatic Index Creation）

如果之前没有创建索引（即：数据库），那么index操作会自动创建一个索引（即：数据库）（手动创建索引，查看create index API），并且还会自动给指定类型（相对于sql中表的概念）创建一个动态类型映射（如果没有创建的话）（手动创建类型映射，查看put mapping）。

映射本身是非常灵活的并且无模式。新的类型和对象将会自动添加到指定类型的映射定义中。查看mapping章节，获取更多关于映射定义的信息。

在所有的节点配置文件中通过设置action.auto_create_index为false来禁用自动索引的创建。通过每个索引作为一个索引设置index.mapper.dynamic为false来禁用自动映射的创建。

自动创建索引包括基于黑/白列表模式，例如，设置action.auto_create_index设置为+aaa*,-bbb*,+ccc*,-*(+表示允许，-表示不允许)。

版本控制（Versioning）

每个索引（新增）的文档都有一个版本号。关联的版本号，是作为返回响应index api请求的一部分。当指定版本参数时，index API可以允许乐观的并发控制。这将控制要执行操作文档的版本号。对于版本控制一个好的用例是执行事务级 先 读 接着 更新 。从读取的原始文档中得到指定的版本号确保此期间（当读取是为了更新时，建议设置preference为_primary）没有发生任何更改。

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

注意：

版本是实时完成的，并且也不会受近实时搜索方法的操作影响。如果没有提供版本，则操作不会对版本进行检查，而是直接执行。当然也可以，使用外部值来指定版本号。（例如，使用数据库中版本号）。要启动这个功能，将version_type设置为external。
提供的值必须是数字，long值，大于等于0，小于9.2e+18。当使用外部版本类型时，系统不会检查匹配的版本号，而是查看通过索引请求通过的版本号是否大于当前文档的版本号。
如果是true，文档将会被索引（插入），并且使用新的版本号。如果提供的值小于等于当前文档的版本号，将会发生版本冲突，并且索引（插入或更新）失败。

警告：

外部版本支持值0作为有效的版本号。这允许在使用外部版本系统同步版本号时，版本号可以是从0开始而不是1。这也有个副作用，只要文档的版本号为0，那么既不能使用Update-By-Query API来更新数据，也不能使用Delete By Query API删除数据。

一个很好的副作用是：只要使用源数据库的版本号，就不需要维护改变源数据库数据的异步索引操作的顺序。如果使用外部版本号，那么从一个数据库里更新elasticsearch索引（即：数据库）数据将会很简单，如果索引（插入）操作是无序的，那么只要使用最新的版本号就可以啦。

版本类型（Version types）

接下来要解释下上面说到的internal（内部）和external（外部）版本类型，elasticsearch也支持特殊用例的其他类型。下面给出了不同版本类型的概要和它们的定义：
①internal（内部）：
如果给定的版本号与（现有的）存储文档的版本号相同，那么其仅仅是索引（插入）文档。

②external 和 external_gt：
如果给定的版本号大于（现有的）存储文档的版本号或者该文档不存在，那么其仅仅只是索引（插入）文档。给定的版本号将作为新的版本号并且存储在新文档中。版本号必须是非负long值。

③external_gte

如果给定的版本号大于等于（现有的）存储文档的版本号，那么其仅仅只是索引（插入）文档。
如果该文档不存在，操作也将成功。给定的版本号将会作为新版本号存储在新文档中。
版本号必须是非负long值。

注意：

external_gte版本类型适用于特殊用例，所以应该谨慎使用。如果使用的不正确，将会造成数据丢失。还有一个选项force，因为会导致主分片和副本分片数据不一致，目前已弃用。

操作类型（Operation Type）

索引操作也能接受一个op_type类型，可用于强制create操作，允许put-if-absent（类似于if else 操作）行为。当使用create时，如果文档早已存在，那么索引（插入）操作将会失败。

下面是使用op_type的例子：

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

指定create的另一个例子：

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

自动id生成（Automatic ID Generation）

索引操作可以在没有指定id的情况下执行。在这种情况下，id将会自动生成。
此外，如果op_type设置为create，id也会自动生成。
下面是例子：（注意：put改为post）

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

上面索引的结果是：

{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    },
    "_index" : "twitter",
    "_type" : "tweet",
    "_id" : "6a8ca01c-7896-48e9-81cc-9f70661fcb32",
    "_version" : 1,
    "created" : true,
    "result": "created"
}

路由（Routing）

默认情况下，分片的放置 — 或者说routing — 通过文档的id哈希值来控制的。
为了更明确的控制，该值可以在每个操作中使用routing参数来直接指定，该值会通过路由器传入到哈希函数中。如下：

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

在上面的例子中，tweet文档会被路由到通过routing参数指定的kimchy分片上。
当设置明确的映射时，使用可选字段_routing，来引导索引操作从文档本身来提取路由值。这是通过额外（非常小的成本）的文档来解析的。
如果定义了_routing映射，并且设置了required，如果没有提供或者提取路由的值，那么索引操作将会失败。

Parents & Children

当创建索引(即：数据库)时，通过指定父项可以检索子文档。如：

PUT blogs
{
  "mappings": {
    "tag_parent": {},
    "blog_tag": {
      "_parent": {
        "type": "tag_parent"//这句意思是blog_tag的父级是tag_parent
      }
    }
  }
}

PUT blogs/blog_tag/1122?parent=1111
{
    "tag" : "something"
}

当索引（插入）子文档时，路由值会自动设置和父级相同（如下），除非使用routing参数明确指出路由值。

{
  "took": 9,
  "timed_out": false,
  "_shards": {
    "total": 5,
    "successful": 5,
    "failed": 0
  },
  "hits": {
    "total": 2,
    "max_score": 1,
    "hits": [
      {
        "_index": "blogs",
        "_type": "blog_tag",
        "_id": "1122",
        "_score": 1,
        "_routing": "1111",//这个和parent值相同
        "_parent": "1111",
        "_source": {
          "tag": "something"
        }
      },
      {
        "_index": "blogs",
        "_type": "blog_tag",
        "_id": "1133",
        "_score": 1,
        "_routing": "1111",//这个和parent值相同
        "_parent": "1111",
        "_source": {
          "tag": "something 1133"
        }
      }
    ]
  }
}

分布式（Distributed）

索引（插入）操作基于路由引导到主分片并且在实际包含这个分片的节点上执行。在主分片完成这个操作之后，如需要的话，分发更新请求给可用副本。

Wait For Active Shards

为了提高系统写入的灵活性，索引操作可以配置为在处理本操作之前，等待活跃分片副本的一定数量。如果所需的分片副本是不可用的，接着写操作必将进行等待和重试，直到所需分片副本启动或者请求超时。默认情况下，写操作在执行之前，只等待活跃的主分片（即：wait_for_active_shards=1）。在索引动态设置中通过设置index.write.wait_for_active_shards可以覆盖默认值。为了修改每个操作的该行为，可以使用请求参数wait_for_active_shards。

有效值是all或者任何一个正整数，总数量是在索引中配置的每个分片副本的数据量（number_of_replicas+1）。指定一个负数或者一个大于分片副本的数量都将是错误的。

例如，假设我们集群中有三个节点：A、B和C。并且我们创建了一个索引index（即：数据库），设置副本的数量为3（结果会有4个分片副本，这个节点上会有多个副本）。如果我们尝试一个索引操作，默认情况下，该操作在处理之前，仅仅确保每个分片中的主分片副本是可利用的。这意味着，即使B、C发送宕机，并且A主机上有主分片副本，该索引在只有一份备份数据下，任会执行。
如果wait_for_active_shards设置为3(并且3个节点全部启动)，接着该索引操作在处理之前，需要三个活跃分片副本，因为在集群中有三个活动节点，其每一个都持有该主分片的副本，所以需求满足。然而，如果我们设置wait_for_active_shards为all（或者设置为4也是一样的），该索引操作将不会执行，因为在索引中的每个活动分片，我们并没有4个副本。这个操作将会请求超时，除非有一个新的节点加入，来持有该分片的第四个副本。

一个重要注意的地方是这个设置会大大的减少写操作不会写入所需数量的分片副本的几率，但是它并不能完全消除这种可能。因为这种检查发生在写操作开始之前。一旦写操作开始了，它仍然可能在任意数量的分片副本上复制失败，但是在主分片仍然会成功。
写操作响应中的_shards表明了复制 成功/失败的分片副本的数量。

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

Refresh

用于控制本次请求所做的更改对搜索而已是可见的。详情看refresh

Noop Updates

当使用index api更新文档时，即使文档并没有变，该文档也会使用新的版本号。（通俗点说，不管你如何操作（更新、插入、删除），文档的版本号，就是会变）。 如果你不想这样，你可以将_update api的detect_noop设置为true。这个选项在index api中是不可用的，因为index api获取不到旧的版本号并且也不能和新的版本号进行比较。

当空更新不可接受时，并没有硬行规定。这是由许多因素组成，比如：你的数据源发送更新(实际是空)的频率和在分片上运行的elasticsearch每秒多少查询与接受多少的更新。

Timeout

分配执行索引操作的主分片可能在执行索引操作时不可用。一些原因是主分片正在从网关中恢复或正在进行迁移。默认情况下，索引操作将会在失败或者响应错误之前会等待主分片一分钟以期待其可以利用。timeout参数用来指定等待时间。下面的例子是设置5分钟。

PUT twitter/tweet/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#timeout