创建文档

PUT /<target>/_doc/<_id>

POST /<target>/_doc/

PUT /<target>/_create/<_id>

POST /<target>/_create/<_id>

创建新的文档，建议使用 _create

路径参数

• target 索引的名称（如果索引不存在，将会自动创建索引）
• _id 文档的id，文档的唯一标识符(注意和我们文档内容中的id字段相区别)

_id 是当前文档对唯一标识，我们文档内容中的id，为存储的数据到字段信息，他们不是必须的对应关系。

常用查询参数

常用，意味着包含但不限于如下的参数

• if_seq_no
  （可选，整数）仅当文档具有此序列号时才执行操作。
• if_primary_term
  （可选，整数）仅当文档具有此主要术语时才执行操作
• refresh （可选，boolean）刷新受影响的分片以使该操作对搜索可见，默认false。建议是false，因为 elastic 间隔一段时间会自动刷新。
• routing（可选，字符串）用于将操作路由到特定分片的自定义值。
• timeout（可选，时间单位）请求等待1. 自动创建索引、2. 动态映射更新、3. 等待活动分片操作的时间。默认为1m（一分钟）
• version（可选，整数）并发控制的显式版本号。指定的版本必须与文档的当前版本相匹配，请求才能成功。更改的乐观锁控制
• wait_for_active_shards （可选，字符串）继续操作之前必须处于活动状态的分片副本数。设置为all或任何正整数，最多为索引中分片的总数 ( number_of_replicas+1)。默认值：1，主分片。
• require_alias （可选，布尔值）为true表示 target 必须是索引别名。默认为false.

示例

PUT /person/_create/1

{
    "id": 1,
    "name":"张三",
    "age": 18,
    "height": 1.75,
    "birthday":"1998-09-10 00:00:00",
    "sex" : 1
}

正常返回结果

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

如果创建id相同的文档，会返回如下结果

{
    "error": {
        "root_cause": [
            {
                "type": "version_conflict_engine_exception",
                "reason": "[1]: version conflict, document already exists (current version [1])",
                "index_uuid": "X2YU2E_dRoGfCdSHYtHYiA",
                "shard": "0",
                "index": "person"
            }
        ],
        "type": "version_conflict_engine_exception",
        "reason": "[1]: version conflict, document already exists (current version [1])",
        "index_uuid": "X2YU2E_dRoGfCdSHYtHYiA",
        "shard": "0",
        "index": "person"
    },
    "status": 409
}

响应说明

• _index
  文档添加到的索引的名称。
• _type
  文档类型。Elasticsearch 索引现在支持单一文档类型，_doc.
• _id
  添加文档的唯一标识符。
• _version
  文档版本。每次更新文档时递增。
• _seq_no
  为索引操作分配给文档的序列号。序列号用于确保文档的旧版本不会覆盖新版本。
• _primary_term
  为索引操作分配给文档的主要术语。
• result
  索引操作的结果，created或updated.
• _shards
  提供有关索引操作的复制过程的信息。
  • total
    指示应在多少分片副本（主分片和副本分片）上执行索引操作。
  • successful
    指示索引操作成功的分片副本数。当索引操作成功时，successful至少为 1。当索引操作成功返回时，副本分片可能不会全部启动。默认情况下，只需要主分片成功即可。可以设置 wait_for_active_shards 来更改默认行为。
  • failed
    如果副本分片上的索引操作失败，则包含与复制相关的错误的数组。0 表示没有失败。

_seq_no 序列号和_primary_term主要术语的作用：当创建、更新或删除文档时，必须将文档的新版本复制到集群中的其他节点。但这些操作是异步的，可能会乱序到达目的地。序列号随着每个操作而增加，因此新操作保证比旧操作具有更高的序列号。elastic 使用序列号和主要术语来唯一标识这些更改。确保较新的文档版本永远不会被分配给它的序列号较小的更改覆盖。

查询文档

GET <index>/_doc/<_id>

HEAD <index>/_doc/<_id>

GET <index>/_source/<_id>

HEAD <index>/_source/<_id>

路径参数编辑

• index
  （必需，字符串）包含文档的索引的名称。
• _id
  （必需，字符串）文档id。

查询参数

• preference
  （可选，字符串）指定应在其上执行操作的节点或分片。默认随机。
• realtime
  （可选，布尔值）true，则请求是实时的，而不是接近实时的。默认为true.
• refresh
  （可选，布尔值）true，则请求在检索文档之前刷新相关分片。默认为false.
• routing
  （可选，字符串）用于将操作路由到特定分片的自定义值。
• stored_fields
  （可选，布尔值）true，检索存储在索引中的文档字段而不是文档_source。默认为false.
• _source
  （可选，字符串）是否返回字段_source，或要返回的字段列表。
• _source_excludes
  （可选，字符串）要从响应中排除的 以逗号分隔的源字段 列表。如果_source参数是false，则忽略此参数。
• _source_includes
  （可选，字符串）要包含在响应中的 以逗号分隔的源字段 列表。如果_source参数是false，则忽略此参数。
• version
  （可选，整数）并发控制的显式版本号。指定的版本必须与文档的当前版本相匹配，请求才能成功。
• version_type
  （可选，枚举）特定版本类型：external， external_gte。

external或者external_gt

如果给定版本严格高于存储文档的版本或者不存在现有文档，则仅索引文档。给定的版本将用作新版本，并将与新文档一起存储。提供的版本必须是一个非负长整数。

external_gte

如果给定版本等于或高于存储文档的版本，则 仅索引文档。如果不存在现有文档，操作也会成功。给定的版本将用作新版本，并将与新文档一起存储。提供的版本必须是一个非负长整数。

示例 1

GET /person/_doc/1

返回结果

{
    "_index": "person",
    "_id": "1",
    "_version": 1,
    "_seq_no": 0,
    "_primary_term": 1,
    "found": true,
    "_source": {
        "id": 1,
        "name": "张三",
        "age": 18,
        "height": 1.75,
        "birthday": "1988-09-10 00:00:00",
        "sex": 1
    }
}

响应说明

• _index
  文档添加到的索引的名称。
• _type
  文档类型。Elasticsearch 索引现在支持单一文档类型，_doc.
• _id
  添加文档的唯一标识符。
• _version
  文档版本。每次更新文档时递增。
• _seq_no
  为索引操作分配给文档的序列号。序列号用于确保文档的旧版本不会覆盖新版本。
• _primary_term
  为索引操作分配给文档的主要术语。
• found
  指示文档是否存在：true或false。
• _routing
  显式路由（如果已设置）。
• _source 文档的信息。如果stored_fields 为 false，显示文档中所有的字段
• _fields 文档字段。如果 stored_fields 为 true，显示包含的文档字段

示例2

GET /person/_source/1

结果

{
    "id": 1,
    "name": "张三",
    "age": 18,
    "height": 1.75,
    "birthday": "1988-09-10 00:00:00",
    "sex": 1
}

可知，_source 的结果就是 _doc 结果对象的 _source 字段

示例3

GET /person/_source/1?_source_includes=id,name

响应结果

{
    "id": 1,
    "name": "张三"
}

更新文档

POST /<index>/_update/<_id>

路径参数

• index
  （必需，字符串）目标索引的名称。
• _id
  （必需，字符串）要更新的文档的 id。

查询参数

• if_seq_no
  （可选，整数）仅当文档具有此序列号时才执行操作。
• if_primary_term
  （可选，整数）仅当文档具有此主要术语时才执行操作
• lang
  （可选，字符串）脚本语言。默认值：painless.
• require_alias
  （可选，布尔值）true 目标必须是索引别名。默认为false.
• retry_on_conflict
  （可选，整数）指定发生冲突时应重试操作的次数。默认值：0。
• refresh
  （可选，布尔值）true，则请求在检索文档之前刷新相关分片。默认为false.
• routing（可选，字符串）用于将操作路由到特定分片的自定义值。
• timeout（可选，时间单位）请求等待1. 自动创建索引、2. 动态映射更新、3. 等待活动分片操作的时间。默认为1m（一分钟）
• wait_for_active_shards （可选，字符串）继续操作之前必须处于活动状态的分片副本数。设置为all或任何正整数，最多为索引中分片的总数 ( number_of_replicas+1)。默认值：1，主分片。
• _source
  （可选，列表）设置为false禁用源检索（默认值：true）。还可以指定要检索的字段列表，以逗号分割。
• _source_excludes
  （可选，列表）指定要排除的源字段。
• _source_includes
  （可选，列表）指定要检索的源字段。

示例1

POST /person/_update/1

{
  "script" : {
    "source": "ctx._source.age += params.skip",
    "lang": "painless",
    "params" : {
      "skip" : 1
    }
  }
}

此方式为使用脚本进行更新，脚本非常简单，就是对 age 属性进行 += skip操作，skip为我们为脚本定义的参数，示例值为1。整个脚本就是为 年龄 + 1的更新操作。

响应结果

{
    "_index": "person",
    "_id": "1",
    "_version": 2,
    "result": "updated",
    "_shards": {
        "total": 2,
        "successful": 1,
        "failed": 0
    },
    "_seq_no": 1,
    "_primary_term": 1
}

重新获取文档后，age 会是 age + 1的值。

示例2

POST /person/_update/1

{
    "doc" : {
        "birthday": "2013-09-10 00:00:00"
    }
}

此方式为直接修改文档，示例只修改了一个属性，当然也可以修改其他属性。

响应结果

{
    "_index": "person",
    "_id": "1",
    "_version": 3,
    "result": "updated",
    "_shards": {
        "total": 2,
        "successful": 1,
        "failed": 0
    },
    "_seq_no": 2,
    "_primary_term": 1
}

如果更新的值与原值一样，会返回 “result”: “noop”，并且version也不会新增。这很有用，我们一般不会禁用此功能。

{
    "_index": "person",
    "_id": "1",
    "_version": 3,
    "result": "noop",
    "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
    },
    "_seq_no": 2,
    "_primary_term": 1
}

禁用noop

请设置请求体为如下

{
    "doc" : {
        "birthday": "2013-09-10 00:00:00"
    },
    "detect_noop" : false
}

mget 获取多个文档

GET /_mget

GET /<index>/_mget

路径参数

• index
  ids（可选，字符串）指定索引或docs数组中的文档未指定索引 时 检索文档的索引名称。

查询参数

• preference
  （可选，字符串）指定应在其上执行操作的节点或分片。默认随机。
• realtime
  （可选，布尔值）true，则请求是实时的，而不是接近实时的。默认为true.
• refresh
  （可选，布尔值）true，则请求在检索文档之前刷新相关分片。默认为false.
• routing
  （可选，字符串）用于将操作路由到特定分片的自定义值。
• stored_fields
  （可选，布尔值）true，检索存储在索引中的文档字段而不是文档_source。默认为false.
• _source
  （可选，字符串）是否返回字段_source，或要返回的字段列表。
• _source_excludes
  （可选，字符串）要从响应中排除的 以逗号分隔的源字段 列表。如果_source参数是false，则忽略此参数。
• _source_includes
  （可选，字符串）要包含在响应中的 以逗号分隔的源字段 列表。如果_source参数是false，则忽略此参数。

请求正文参数说明

• docs 包含如下字段的对象数组。请求中未指定索引时，则必须使用该参数以确定查询哪些索引的哪些文档甚至对应的字段。
  • _id
    （必需，字符串）唯一的文档 ID。
  • _index
    （可选，字符串）包含文档的索引。如果请求 URI 中未指定索引，则为必需。
  • routing
    （可选，字符串）文档所在的主分片的键。如果在索引期间使用路由，则需要。
  • _source
    （可选，布尔值）如果false，则排除所有_source字段。默认为true.
    • source_include
      （可选，数组）要从字段中提取和返回的字段_source。
    • source_exclude
      （可选，数组）要从返回字段中排除的字段_source。
  • _stored_fields
    （可选，数组）要检索的存储字段。
• ids 要使用该参数，请求中需要指定索引，数组类型的文档_id列表，如：[“1”,“2”]

示例1

GET /_mget

{
    "docs": [{
        "_id": "1",
        "_index":"person"
    },{
        "_id": "1",
        "_index":"users"
    }]
}

响应结果

{
    "docs": [
        {
            "_index": "person",
            "_id": "1",
            "_version": 5,
            "_seq_no": 4,
            "_primary_term": 1,
            "found": true,
            "_source": {
                "id": 1,
                "name": "张三",
                "age": 19,
                "height": 1.75,
                "birthday": "2013-09-10 00:00:00",
                "sex": 1
            }
        },
        {
            "_index": "users",
            "_id": "1",
            "error": {
                "root_cause": [
                    {
                        "type": "index_not_found_exception",
                        "reason": "no such index [users]",
                        "resource.type": "index_or_alias",
                        "resource.id": "users",
                        "index_uuid": "_na_",
                        "index": "users"
                    }
                ],
                "type": "index_not_found_exception",
                "reason": "no such index [users]",
                "resource.type": "index_or_alias",
                "resource.id": "users",
                "index_uuid": "_na_",
                "index": "users"
            }
        }
    ]
}

如果对应的索引不存在，则会返回错误信息

如果索引存在，但是文档不存在，则返回如下信息

{
    "docs": [
        {
            "_index": "person",
            "_id": "1",
            "_version": 5,
            "_seq_no": 4,
            "_primary_term": 1,
            "found": true,
            "_source": {
                "id": 1,
                "name": "张三",
                "age": 19,
                "height": 1.75,
                "birthday": "2013-09-10 00:00:00",
                "sex": 1
            }
        },
        {
            "_index": "users",
            "_id": "1",
            "found": false
        }
    ]
}

示例2

GET /person/_mget

{
    "ids": ["1","2"]
}

删除文档

DELETE /<index>/_doc/<_id>

路径参数

• index
  （必需，字符串）目标索引的名称。
• _id
  （必需，字符串）文档的唯一标识符。

查询参数

• if_seq_no
  （可选，整数）仅当文档具有此序列号时才执行操作。
• if_primary_term
  （可选，整数）仅当文档具有此主要术语时才执行操作。
• refresh
• routing
• timeout 默认1m，1分钟
• version
  （可选，整数）并发控制的显式版本号。指定的版本必须与文档的当前版本相匹配，请求才能成功。
• version_type
  （可选，枚举）特定版本类型：external， external_gte。
• wait_for_active_shards
  （可选，字符串）在继续操作之前必须处于活动状态的分片副本数。设置为all或任何正整数，最多为索引中分片的总数 ( number_of_replicas+1)。默认值：1，主分片。

在文档上执行的每个写操作，包括删除，都会导致其版本增加。已删除文档的版本号在删除后的短时间内仍然可用，以允许控制并发操作。已删除文档的版本保持可用的时间长度由index.gc_deletes索引设置决定，默认为 60 秒。

我们可以使用 if_seq_no + if_primary_term 来控制并发删除。如果检测到不匹配，该操作将产生VersionConflictException 409 状态代码。

示例1 开放式并发控制更新或删除

DELETE /person/_doc/1?if_seq_no=2&if_primary_term=1

我们的person 1 目前的 _seq_no = 4，_primary_term = 1，所以当前的删除请求是失败的

响应结果

{
    "error": {
        "root_cause": [
            {
                "type": "version_conflict_engine_exception",
                "reason": "[1]: version conflict, required seqNo [2], primary term [1]. current document has seqNo [4] and primary term [1]",
                "index_uuid": "X2YU2E_dRoGfCdSHYtHYiA",
                "shard": "0",
                "index": "person"
            }
        ],
        "type": "version_conflict_engine_exception",
        "reason": "[1]: version conflict, required seqNo [2], primary term [1]. current document has seqNo [4] and primary term [1]",
        "index_uuid": "X2YU2E_dRoGfCdSHYtHYiA",
        "shard": "0",
        "index": "person"
    },
    "status": 409
}

示例2：版本控制更新或删除

DELETE /person/_doc/1?version=2&version_type=external

我们文档当前版本为version = 4，当前的示例请求也是会失败的

响应结果

{
    "error": {
        "root_cause": [
            {
                "type": "version_conflict_engine_exception",
                "reason": "[1]: version conflict, current version [5] is higher or equal to the one provided [2]",
                "index_uuid": "X2YU2E_dRoGfCdSHYtHYiA",
                "shard": "0",
                "index": "person"
            }
        ],
        "type": "version_conflict_engine_exception",
        "reason": "[1]: version conflict, current version [5] is higher or equal to the one provided [2]",
        "index_uuid": "X2YU2E_dRoGfCdSHYtHYiA",
        "shard": "0",
        "index": "person"
    },
    "status": 409
}

示例3：直接删除

DELETE /person/_doc/1

索引重建

索引重建，类似于表的拷贝，在更新现有索引映射类型的时候常常需要索引重建。因为修改现有索引映射字段的类型时，可能会使已编制索引的数据无效。但有时我们不得不修改现有索引映射字段类型时，可以通过索引重建的方式来防止已有数据的索引无效的问题。

POST /_reindex

查询参数

• refresh
  （可选，布尔值）true，则请求刷新受影响的分片以使此操作对搜索可见。默认为false.
• timeout
  （可选，时间单位） 默认为1m（一分钟）。这保证 Elasticsearch 在失败之前至少等待超时。实际等待时间可能会更长，尤其是发生多次等待时。
• wait_for_active_shards
  （可选，字符串）在继续操作之前必须处于活动状态的分片副本数。设置为all或任何正整数，最多为索引中分片的总数 ( number_of_replicas+1)。默认值：1，主分片。
• wait_for_completion
  （可选，布尔值）如果true，请求将阻塞直到操作完成。默认为true.
• requests_per_second
  （可选，整数）每秒子请求数中此请求的限制。默认为-1（无限制）
• require_alias
  （可选，布尔值）如果true，目标必须是索引别名。默认为false.
• scroll
  （可选，时间单位）指定应为滚动搜索维护索引的一致视图多长时间。
• slices
  （可选，整数）此任务应分为的切片数。默认为 1，表示任务不被分割成子任务。
• max_docs
  （可选，整数）要处理的最大文档数。默认为所有文档。当设置为小于或等于的值时，scroll_size将不会使用滚动来检索操作的结果。

请求正文

• conflicts
  （可选，枚举）设置为proceed继续重建索引，即使存在冲突。默认为abort.

• max_docs
  （可选，整数）要重建索引的最大文档数。如果conflicts等于 proceed，则 reindex 可能会尝试从源中重新索引更多的文档，直到max_docs它成功地将文档索引max_docs到目标中，或者它已经遍历了源查询中的每个文档。

• source

  • index
    （必需，字符串）要从中 复制的数据流、索引或别名的名称 。还接受以逗号分隔的列表以从多个来源重新编制索引。
  • query
    （可选，查询对象）指定要使用查询 DSL 重新编制索引的文档。
  • remote
    • host
      （可选，字符串）要从中 编制索引的 Elasticsearch 远程实例的 URL 。从远程 Elasticsearch 重建时需要
    • username
      （可选，字符串）用于对远程主机进行身份验证的用户名。
    • password
      （可选，字符串）用于对远程主机进行身份验证的密码。
    • socket_timeout
      （可选，时间单位）远程套接字读取超时。默认为 30 秒。
    • connect_timeout
      （可选，时间单位）远程连接超时时间。默认为 30 秒。
    • headers
      （可选，对象）包含请求标头的对象。
  • size
    {可选，整数）每批要索引的文档数。从远程建立索引时使用，以确保批次适合堆上缓冲区，默认最大大小为 100 MB。
  • slice
    • id
      （可选，整数）手动切片的切片 ID 。
    • max
      （可选，整数）切片总数。
  • _source
    （可选，字符串）true重新索引所有源字段。设置为列表以重新索引选择字段。默认为true.

• dest 来源

  • index
    （必需，字符串）要复制到的 数据流、索引或索引别名的名称。
  • version_type
    （可选，枚举）用于索引操作的版本控制。有效值：internal、external、external_gt、external_gte。
  • op_type
    （可选，枚举）设置为仅创建不存在的索引文档（如果不存在则放置）。有效值：index, create。默认为index.
  • pipeline
    （可选，字符串）要使用的 管道 的名称。

• script

  • source
    （可选，字符串）重建索引时运行以更新文档源或元数据的脚本。
  • lang
    （可选，枚举）脚本语言：painless, expression, mustache, java.

响应说明

• took
  （整数）整个操作花费的总毫秒数。
• timed_out
  (Boolean)如果在重新索引期间执行的任何请求超时，则为true。
• total
  （整数）成功处理的文档数。
• updated
  （整数）成功更新的文档数，即在重新索引更新之前已经存在具有相同 ID 的文档。
• created
  （整数）成功创建的文档数。
• deleted
  （整数）成功删除的文档数。
• batches
  （整数）重新索引拉回的滚动响应数。
• noops
  noop（整数）由于用于重建索引的脚本返回了的值 而被忽略的文档数。
• version_conflicts
  （整数）重新索引命中的版本冲突数。
• retries
  （整数）重新索引尝试的重试次数。bulk是重试的批量操作的数量，search是重试的搜索操作的数量。
• throttled_millis
  （整数）请求睡眠以符合的毫秒数requests_per_second。
• requests_per_second
  （整数）重建索引期间每秒有效执行的请求数。
• throttled_until_millis
  （整数）此字段在响应中应始终等于零_reindex。它仅在使用Task API时才有意义，它指示下一次再次执行请求的毫秒数.
• failures
  （数组）如果在此过程中出现任何不可恢复的错误，则为失败数组。如果这是非空的，那么请求会因为这些失败而中止。Reindex 是使用批处理实现的，任何失败都会导致整个过程中止，但当前批处理中的所有失败都会收集到数组中。可以使用conflicts选项来防止重新索引在版本冲突时中止。

先创建目标索引

索引重建，不会从源或其关联模板复制设置。因此，须提前配置映射、分片计数、副本等。所以我们先创建一个目标索引，设置好响应的设置，然后再 _reindex

示例：我们创建一个目标索引 person1

PUT /person1
{
    "mappings": {
        "properties": {
            "age": { 
                "type": "integer"
            },  
            "birthday":  { 
                "type": "date",
                "format":"yyyy-MM-dd HH:mm:ss" 
            }, 
            "name":   { 
                "type": "text"  
            },
            "height": {
                "type": "float"
            },
            "id": {
                "type": "long"
            },
            "sex":{
                "type": "byte"
            }
        }
    }
}

此处我们设置了新的映射，该映射name属性映射为了text类型。

索引重建

POST /_reindex

{
  "source": {
    "index": "person"
  },
  "dest": {
    "index": "person1"
  }
}

响应信息

{
    "took": 296,
    "timed_out": false,
    "total": 1,
    "updated": 0,
    "created": 1,
    "deleted": 0,
    "batches": 1,
    "version_conflicts": 0,
    "noops": 0,
    "retries": {
        "bulk": 0,
        "search": 0
    },
    "throttled_millis": 0,
    "requests_per_second": -1,
    "throttled_until_millis": 0,
    "failures": []
}