将JSON文档添加到指定的数据流或者索引并使其可搜索。如果目标是索引并且文档已经存在，则请求更新文档并增加其版本。

注意：

你不可以使用索引文档API去对现有文档发送更新请求到数据流。参阅使用query在数据流中更新文档和更新或者删除备份索引中的文档。

请求

PUT /<target>/_doc/<_id>

POST /<target>/_doc/

PUT /<target>/_create/<_id>

POST /<target>/_create/<_id>

重要

你不可以使用PUT /<target>/_doc/<_id>请求格式向数据流添加新的文档。指定文档ID，使用PUT /<target>/_create/<_id>代替。参阅向数据流中添加文档。

数据流笔者之前也没接触过，官方文档描述：

数据据流让你在多个索引中存储仅有附加的时间序列数据，同时给你一个单一的命名资源来进行请求。数据流非常适用于日志、事件、指标和其他连续产生的数据。你可以直接向数据流提交索引和搜索请求。数据流会自动将请求路由到存储数据流的备份索引。你可以使用索引生命周期管理（ILM）来自动管理这些支持索引。

先决条件

如果ElasticSearch安全功能是开启，你必须对目标数据流、索引、索引别名拥有以下权限：
- 要使用PUT /<target>/_doc/<_id>添加或者覆盖文档的话，你必须拥有create、index或者写索引的权限。
- 使用POST /<target>/_doc/，PUT /<target>/_create/<_id>，POST /<target>/_create/<_id>添加文档的话，你必须拥有create_doc，create，index，或者write索引权限。
- 使用index API请求自动创建一个数据流或者索引，你必须有auto_configure,create_index,manage索引权限。
自动数据流创建需要启动data stream的匹配的索引模板。参阅设置数据流。

地址参数

<target>(必须，字符串)目标数据流或者索引名称。

如果目标不存在，并且与带有data_stream定义的索引模板的名称或通配符(*)模式匹配，该请求会创建数据流。参阅设置数据流。

如果目标不存在并且没有和数据流模板匹配，该请求会创建一个索引。

你可以使用解析索引api检查目标是否存在。
<_id>(必须，字符串)文档的唯一标识符使用POST /<target>/_doc/请求可以自动创建文档ID。

请求参数

if_seq_no(可选，integer)

仅当文档有这个序列号时才执行这个操作。参阅乐观并发控制。
if_primary_term(可选，integer)

仅当文档有这个序列号时才执行这个操作。参阅乐观并发控制。
op_type(可选，枚举)

设置create仅当文档不存在时索引文档（如果不存在则put）。如果携带特定_id的文档已经存在，索引操作将失败。和使用<index>/_create端点一样。有效值：index，create。如果文档id是被指定，默认为index。其他情况默认为create。

注意

请求目标为数据流的话，op_type的create是被需要的，参阅向数据流中添加文档。
pipeline(可选，字符串)

用于预处理输入文档的管道ID。

可以理解为spring中的before切面
refresh(可选，枚举)

如果为true，ElasticSearch刷新受影响的分片去使操作结果可见，如果wait_for然后等待刷新去使查询可见操作结果，如果为false则不做任何刷新。有效值：true，false,wait_for。默认为false。
routing(可选，字符串)指导操作路由到特定分片。
timeout(可选，时间单位)

请求等待一下操作的时间段：
- Automatic index creation
- Dynamic mapping 更新
- 等待活跃分片
默认为1m（1分钟）。Elasticsearch担保在失败前至少等待的超时时间。实际等待时间更长，特别当多个等待发生时。
version（可选，integer）

并发控制的确切版本数。只有当指定的版本和当前文档版本匹配时请求才会成功。
version_type(可选，enum)指定版本类型：external, external_gte。
wait_for_active_shards（可选，字符串）

在继续操作前必须处于活跃状态的分片副本数。设置为all或者任何一个整数最高为索引的分片总数（number_of_replicas+1）。默认为1，主分片。

参阅活跃分片。
require_alias(可选，boolean)

如果为true，目标必须是一个索引别名，默认为false。

请求体

<filed>(必填，字符串)

请求体包含文档数据的JSON source。

响应体

_shards 提供关于索引操作的副本处理信息。
_shard.total

表明索引操作应该被执行在多少分片副本上（主分片和副本分片）
_shards.sucessful

表明索引操作在多少分片副本上执行成功。当索引操作successful，至少成功一个。

注意当索引操作返回成功时也许副本分片没有全部开始，默认只要求主分片操作成功。设置wait_for_active_shards改变默认行为。参阅活跃分片。
_shards.failed

在副本分片上索引操作失败时包含副本相关错误的一个数组。0表明没有错误。
_index 添加文档到其中的索引名。
_type

文档类型。Elasticsearch表明现在只支持一种文档类型，_doc。
_id

被插入文档的唯一标识。
_version

文档版本。文档被更新时递增。
_seq_no

索引操作的文档被分片的序号。序号被用于确保文档的旧版本不会被一个新版本覆盖。参阅乐观并发控制。
_primary_term 索引操作的文档被分配的primary_term。
result 索引操作的结果，created或者updated。

例子

这里使用《ElasticSearch之安装上手》中使用logstash导入的movies索引。

`PUT /<target>/_doc/<_id>`

PUT movies/_doc/100000
{
 "genre" : [
            "Comedy"
          ],
          "year" : 1897,
          "title" : "dsd"
}

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

再试一次，返回结果：

{
  "_index" : "movies",
  "_type" : "_doc",
  "_id" : "100000",
  "_version" : 2,
  "result" : "updated",
  "_shards" : {
    "total" : 2,
    "successful" : 2,
    "failed" : 0
  },
  "_seq_no" : 312130,
  "_primary_term" : 7
}

`POST /<target>/_doc/`

POST movies/_doc
{
 "genre" : [
            "Comedy"
          ],
          "year" : 1897,
          "title" : "dsd"
}

返回结果：

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

可以看到自动分配了id

`PUT /<target>/_create/<_id>`

试下前面插入过的id

PUT movies/_create/100000
{
 "genre" : [
            "Comedy"
          ],
          "year" : 1897,
          "title" : "dsd"
}

返回结果：

{
  "error" : {
    "root_cause" : [
      {
        "type" : "version_conflict_engine_exception",
        "reason" : "[100000]: version conflict, document already exists (current version [2])",
        "index_uuid" : "0ffu5E08T8GxBazfh5t0Dg",
        "shard" : "0",
        "index" : "movies"
      }
    ],
    "type" : "version_conflict_engine_exception",
    "reason" : "[100000]: version conflict, document already exists (current version [2])",
    "index_uuid" : "0ffu5E08T8GxBazfh5t0Dg",
    "shard" : "0",
    "index" : "movies"
  },
  "status" : 409
}

PUT movies/_create/100002
{
 "genre" : [
            "Comedy"
          ],
          "year" : 1897,
          "title" : "dsd"
}

返回结果：

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

`POST /<target>/_create/<_id>`

POST movies/_create/100004
{
 "genre" : [
            "Comedy"
          ],
          "year" : 1897,
          "title" : "dsd"
}

返回结果：

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

第一个PUT /<target>/_doc/<_id>应该是最常用的，其次应该是POST /<target>/_doc/。PUT /<target>/_create/<_id>和POST /<target>/_create/<_id>目前感觉没啥区别，从restful接口规范来说，post才会新增。

文档

Index API

开启掘金成长之旅！这是我参与「掘金日新计划 · 2 月更文挑战」的第 5 天，点击查看活动详情

Elasticsearch之Index API

请求

先决条件

地址参数

请求参数

请求体

响应体

例子

PUT /<target>/_doc/<_id>

POST /<target>/_doc/

PUT /<target>/_create/<_id>

POST /<target>/_create/<_id>

文档

`PUT /<target>/_doc/<_id>`

`POST /<target>/_doc/`

`PUT /<target>/_create/<_id>`

`POST /<target>/_create/<_id>`