创建文档

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 /_mgetGET /<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": []
}