Elasticsearch REST APIs-Document APIs

 

Document APIs 

 

Index 向index、data stream新增文档。如果目标是index且文档ID已存在，则覆盖。

PUT /<target>/_doc/<_id>

POST /<target>/_doc/

PUT /<target>/_create/<_id>　　当文档不存在时起作用

POST /<target>/_create/<_id>

如果target是data stream，则如果指定ID则不能使用PUT /<target>/_doc/<_id>，应使用PUT /<target>/_create/<_id>

 

path参数：

<target>(必须, string) data stream 、 index 的名称.

　　如果target不存在，且与data stream的index template的名称或 wildcard (*) 匹配，则自动创建对应的data stream。

　　如果target不存在，且与data stream的template的名称规则不匹配，则自动创建index。

<_id>(可选, string) 文档的唯一ID，不指定ID时使用 POST /<target>/_doc  。

query参数：

if_seq_no(可选, integer) 只有当index的if_seq_no是该值时才会处理该文档，否则409 Version Conflict。乐观锁控制，因为index每处理一个文档就会if_seq_no+1。

if_primary_term(可选, integer) 只有当该文档所在的primary分片号是if_primary_term时才会处理该文档，否则409 Version Conflict。乐观锁控制。

op_type(可选, enum)当设置为 create 时的处理机制是文档不存在才处理 (相当于put if absent)，如果文档已存在，处理会失败。可选值 index, create.

当ID指定时，默认值=index ， 否则默认=create

pipeline(可选, string) 指定一个pipeline的ID来触发.

refresh(可选, enum)

true：立即刷新关联的shard。

wait_for：等待response直到index刷新。

false：默认，无处理。

routing(可选, string) 分片的路由参数.

timeout(可选, time units) 对以下动作的超时时间，默认1m:

• Automatic index creation
• Dynamic mapping updates
• Waiting for active shards

version(可选, integer) 乐观锁，指定ID时使用.

version_type(可选, enum) Specific version type: external, external_gte.

wait_for_active_shards(可选, string) 这个参数覆盖了index.write.wait_for_active_shards。

预先检查shard的可用数量，如果当时可用的shard数量小于配置数，则ES会重试直到超时，默认1即只需primary，可选all或 1 - number_of_replicas+1 。

因为文档在索引时会从primary尽力的同步到各个可用的replica，所以该配置是预先检查机制，提供数据的可靠性。

require_alias(可选, Boolean) 如果是true，则要求目标是一个index的别名。默认false.

request body参数：json

response body参数：

_shards 分片信息.

_shards.total 总的分片数量primary and replica shards.

_shards.successful 成功的分片数量，当操作成功时，successful至少是1。

_shards.failed 失败的分片数量，0表示没有失败。

_index index的名称。

_id 文档的ID.

_version 文档的版本.

_seq_no 对应的index的_seq_no.

_primary_term primary分片号.

result 处理结果是 created or updated.

 

Get 通过ID获取文档

GET <index>/_doc/<_id>　　完整文档信息

HEAD <index>/_doc/<_id>　　存在200，否则404

GET <index>/_source/<_id>　　只含_source

HEAD <index>/_source/<_id>　　存在200，否则404

 

关于实时性：

默认情况下该系列API是实时的，不受index的refresh 影响；如果请求存储字段，并且文档已更新但尚未刷新，则get API必须解析和分析源以提取存储字段，为了禁用实时获取，可以将realtime参数设置为false。

 

path参数：

<index>(必须, string) 索引名称.

<_id>(必须, string) 文档ID.

 

query参数：

preference(可选, string) 指定在哪个node或shard上执行，默认随机.

realtime(可选, Boolean) 是否实时，默认true.

refresh(可选, Boolean)如果为true，则请求在检索文档之前刷新相关碎片。默认为false。

routing(可选, string) 路由参数，到哪个shard.

stored_fields(可选, Boolean) 如果为true，则检索存储在索引中的文档字段，而不是文档 _source.默认false。

_source(可选, string) 是否返回_source，默认true.

_source_excludes(可选, string) 响应中在_source排除哪些字段，逗号分割.当_source 是false时不起作用。

_source_includes(可选, string) 跟_source_excludes相反。

version(可选, integer) 指定version控制并发，version必须与文档当前的version匹配否则失败。

version_type(可选, enum) Specific version type: external, external_gte.

 

response body参数：

_index index名称.

_id 文档ID.

_version 文档版本.

_seq_no 对应的index的_seq_no.

_primary_term 分片号.

found 文档是否存在: true or false.

_routing 指定的路由，如果有设置的话.

_source 当文档存在时返回，除非参数_source是false或stored_fields是true.

_fields 如果stored_fields是true 且文档存在.

 

Delete 删除指定ID的文档

DELETE /<index>/_doc/<_id>

 关于并发控制乐观锁：可用if_seq_no和 if_primary_term 来控制，当不匹配时响应409 Version Conflict。

 

path参数：

<index>(必须, string) index名称.

<_id>(必须, string) 文档ID.

 

query参数：

if_seq_no(Optional, integer) 同上.

if_primary_term(Optional, integer) 同上.

refresh(Optional, enum)默认false

　　true，refresh相关的shards.

　　wait_for wait直到refresh。

　　false do nothing with refreshes.

routing(Optional, string) 如果文档是有路由的，则必须指定相同的规则参数，否则RoutingMissingException .

timeout(Optional, time units) wait for active shards的时间. 默认1m.

version(Optional, integer) 指定版本号乐观锁.

version_type(Optional, enum) Specific version type: external, external_gte.

wait_for_active_shards(Optional, string) 默认1即只需primary，可选all或 1 - number_of_replicas+1 。

 

response body:

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_type": "_doc",
  "_id": "1",
  "_version": 2,
  "_primary_term": 1,
  "_seq_no": 5,
  "result": "deleted"
}

 

Delete by query 通过条件删除文档

POST /<target>/_delete_by_query

条件可以使用Search API 在query参数和body参数中。

 

path参数：

<target>(Optional, string) data streams, indices, and aliases 的逗号分割. 可以使用通配符*或_all.

 

query参数：

allow_no_indices(Optional, Boolean)是否允许匹配不到index，如果false则匹配不到时失败，例如target是foo*,bar*，实际存在foo开头的index但没有bar开头的就会失败，默认true.

analyzer(Optional, string) query的分词器，只能在 q 参数指定时使用.

analyze_wildcard(Optional, Boolean) If true, wildcard and prefix queries are analyzed. Defaults to false.只能在 q 参数指定时使用.

conflicts(Optional, string) 当版本冲突时怎么处理: abort or proceed. 默认 abort.

default_operator(Optional, string) 条件关系: AND or OR. 默认 OR.只能在 q 参数指定时使用.

df(Optional, string) Field to use as default where no field prefix is given in the query string.只能在 q 参数指定时使用.

expand_wildcards(Optional, string) 可以被通配符匹配的索引，逗号分割，默认open，可选值:

all

Match any data stream or index, including hidden ones.

open

Match open, non-hidden indices. Also matches any non-hidden data stream.

closed

Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.

hidden

Match hidden data streams and hidden indices. Must be combined with open, closed, or both.

none

Wildcard patterns are not accepted.

from(Optional, integer) 匹配文档的offset. 默认 0.

ignore_unavailable(Optional, Boolean) 如果true, 响应中不包含missing or closed indices.默认false.

lenient(Optional, Boolean) 错误容忍，如果true,忽略query的格式错误（比如给数字类型使用text） .默认false.只能在 q 参数指定时使用.

max_docs(Optional, integer) 最多删除文档数量，默认全部.

preference(Optional, string) 指定在哪个node或shard上执行，默认随机.

q(Optional, string) Query in the Lucene query string syntax.

request_cache(Optional, Boolean) If true, the request cache is used for this request. Defaults to the index-level setting.

refresh(Optional, Boolean) 如果 true, 请求完成后refresh所有shard，而不是Delete API的刷新相关shard，默认 false.

requests_per_second(Optional, integer) 删除处理的每秒处理数量，默认-1不限制.

routing(Optional, string) Custom value used to route operations to a specific shard.

scroll(Optional, time value) delete by query使用scroll查询，该参数控制scroll该次的生命周期，默认5m. 见Scroll search results.

scroll_size(Optional, integer) scroll的Size。默认1000.

search_type(Optional, string) The type of the search operation. Available options:

• query_then_fetch
• dfs_query_then_fetch

search_timeout(Optional, time units) search的超时时间，默认不超时.

slices(Optional, integer) 是否需要拆分成子任务，默认1不拆分.

sort(Optional, string) 查询的排序，逗号分割， <field>:<direction> pairs.

_source(Optional, string) True or false 控制是否return _source ，或者指定字段集.

_source_excludes(可选, string) 响应中在_source排除哪些字段，逗号分割.当_source 是false时不起作用。

_source_includes(可选, string) 跟_source_excludes相反。

stats(Optional, string) Specific tag of the request for logging and statistical purposes.

terminate_after(Optional, integer) 每个shard允许搜集的最大文档数量，当到达最大数量时提前结束query.

timeout(Optional, time units) 超时时间 waits for active shards. 默认1m.

version(Optional, Boolean) 如果true, 返回文档的version.

wait_for_active_shards(Optional, string) 默认1即只需primary，可选all或 1 - number_of_replicas+1 。

 

request body：

query(Optional, query object) json Query DSL.

 

response body：

took 整个操作的耗时ms.

timed_out 是否超时.

total 成功处理的文档数量.

deleted 成功删除的文档数量.

batches The number of scroll responses pulled back by the delete by query.

version_conflicts 版本冲突的数量.

noops 对于该API一直是0.

retries The number of retries attempted by delete by query. bulk is the number of bulk actions retried, and search is the number of search actions retried.

throttled_millis 总的对requests_per_second的sleep节流ms.

requests_per_second 删除处理的每秒处理数量.

throttled_until_millis 该API一直是0.

failures 处理过程中的不可重试的失败。

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

 

Update 更新指定的文档

POST /<index>/_update/<_id>

该API允许通过script更新、删除或跳过一些文档，也可以更新部分指定的文档字段，如果需要完全覆盖已存在的文档则要使用Index API。

要使用update，索引的_source必须是enable的。

当使用script时，可以直接访问元数据 ctx : _index, _type, _id, _version, _routing, 还有 _now (当前时间戳).

 

path参数：

<index>(必须, string) index名称，默认如果index不存在自动创建。

<_id>(必须, string) 文档ID.

 

query参数：

if_seq_no(Optional, integer) 同上.

if_primary_term(Optional, integer) 同上.

lang(Optional, string) script 的语言类型. 默认: painless.

require_alias(Optional, Boolean) 如果true, 目标必须是 index alias. 默认 false.

refresh(可选, enum)

　　true：立即刷新关联的shard。

　　wait_for：等待response直到index刷新。

　　false：默认，无处理。

retry_on_conflict(Optional, integer) 当并发更新版本冲突时的重试次数，默认0，如果达到重试次数还是冲突则409.

routing(Optional, string) 如果文档有routing时则必须指定.

_source(Optional, list) Set to false to disable source retrieval (default: true). You can also specify a comma-separated list of the fields you want to retrieve.

_source_excludes(Optional, list) 同上.

_source_includes(Optional, list) 同上.

timeout(Optional, time units) 以下操作的等待时间，默认1m:

• Dynamic mapping updates
• Waiting for active shards

wait_for_active_shards(Optional, string)同上。

 

Update by query 条件更新文档

POST /<target>/_update_by_query

可以使用script、pipeline作为更新。

总体机制与 Delete by query相似，path、query、request body、response body（多了一个updated参数）的参数全部相同。

 

Multi get 通过IDs get多个文档，可以从多个index中get

GET /_mget

GET /<index>/_mget

 

path参数：

<index>(Optional, string) index的名称，如果不指定则在body中指定.

 

query参数：

preference(Optional, string) 指定在哪个node或shard上执行，默认随机.

realtime(Optional, Boolean) 是否实时，默认true.

refresh(Optional, Boolean) 如果为true，则请求在检索文档之前刷新相关碎片。默认为false。

routing(Optional, string) 分片路由参数.

stored_fields(Optional, Boolean) 如果为true，则检索存储在索引中的文档字段，而不是文档 _source.默认false。

_source(可选, string) 是否返回_source，默认true.

_source_excludes(可选, string) 响应中在_source排除哪些字段，逗号分割.当_source 是false时不起作用。

_source_includes(可选, string) 跟_source_excludes相反。

 

request body:

docs(Optional, array) 当path参数没有指定index时必须:

　　_id(Required, string) 文档ID.

　　_index(Optional, string) 当path参数没有指定index时必须.

　　routing(Optional, string) 如果文档有routing则必须，否则找不到.

　　_source(Optional, Boolean) 是否需要_source，默认true.

source_include(Optional, array) 响应中在_source排除哪些字段，逗号分割.当_source 是false时不起作用。

source_exclude(Optional, array)跟_source_excludes相反。

　　_stored_fields(Optional, array) The stored fields you want to retrieve.

ids(Optional, array) 文档的IDs，当path参数指定index时使用。

 

response body：响应是一个 docs array，每个文档的结构与Get API的响应类似。

 

Bulk 在单个API调用中执行多个操作。减少开销，可以大大提高索引速度

POST /_bulk

POST /<target>/_bulk

同时允许的操作包括：index, create, delete, and update 。

request body 使用 newline delimited JSON (NDJSON):

index 和 create 需要一个 source 在下一行,结构与Index API一样: create 操作如果在文档已存在时会失败, index 将会增加或覆盖文档.

update 要求在下一行指定doc、upsert和script及其参数.

delete 不需要在下一行出现source，并且具有与标准Delete API相同的语义.

 

path参数：

<target>(Optional, string) data stream, index, 或 index alias 的名称.

 

query参数：

pipeline(Optional, string) 需要给incoming文档使用的pipeline的ID.

refresh(可选, enum)

　　true：立即刷新关联的shard。

　　wait_for：等待response直到index刷新。

　　false：默认，无处理。

require_alias(Optional, Boolean) 如果true, target 必须是 index alias. 默认 false.

routing(可选, string) 分片的路由参数.

_source(可选, string) 是否返回_source，默认true.

_source_excludes(可选, string) 响应中在_source排除哪些字段，逗号分割.当_source 是false时不起作用。

_source_includes(可选, string) 跟_source_excludes相反。

timeout(可选, time units) 对以下动作的超时时间，默认1m:

• Automatic index creation
• Dynamic mapping updates
• Waiting for active shards

wait_for_active_shards(可选, string) 这个参数覆盖了index.write.wait_for_active_shards。预先检查shard的可用数量，如果当时可用的shard数量小于配置数，则ES会重试直到超时，默认1即只需primary，可选all或 1 - number_of_replicas+1 。

因为文档在索引时会从primary尽力的同步到各个可用的replica，所以该配置是预先检查机制，提供数据的可靠性。

 

request body:

create(Optional, string) 创建文档.

　　_index(Optional, string) data stream, index, or index alias的名称. 当 <target> 没有指定时必须.

　　_id(Optional, string) 文档的ID，如果不指定则使用自动ID.

　　require_alias(Optional, Boolean) 如果true, target 必须是 index alias. 默认 false.

　　dynamic_templates(Optional, map) 动态模板，与Index Mapping的动态模板类似。

delete(Optional, string) 删除文档.

　　_index(Optional, string)data stream, index, or index alias的名称. 当 <target> 没有指定时必须.

　　_id(Required, string) 文档 ID.

　　require_alias

(Optional, Boolean) 如果true, target 必须是 index alias. 默认 false.

index(Optional, string) 索引文档.

　　_index(Optional, string) data stream, index, or index alias的名称. 当 <target> 没有指定时必须.　　

　　_id(Optional, string) 文档的ID，如果不指定则使用自动ID.　　

　　require_alias(Optional, Boolean) 如果true, target 必须是 index alias. 默认 false.　　

　　dynamic_templates(Optional, map) 动态模板，与Index Mapping的动态模板类似。

update(Optional, string) 更新文档.

　　_index(Optional, string)data stream, index, or index alias的名称. 当 <target> 没有指定时必须.　　

　　_id(Required, string) 文档 ID.　　

　　require_alias(Optional, Boolean) 如果true, target 必须是 index alias. 默认 false.

doc(Optional, object) 文档的一部分,用于 update.　　例如 { "doc" : {"field2" : "value2"} }

<fields>(Optional, object) 文档的一部分,用于 create 和index .　　例如 { "field1" : "value1" }

 

response body：bulk API的响应包含请求中每个操作的单独结果，并以提交的顺序返回。单个操作的成功或失败不会影响请求中的其他操作。为了确保快速响应，如果一个或多个shard失败，bulk API将响应部分结果。参考 Shard failures 。

took(integer) 耗时ms.

errors(Boolean) 如果 true, 表示至少有一个操作失败.

items(array of objects) 每个操作的单独结果，并以提交的顺序返回.

　　<action>(object) 即操作的类型： create, delete, index, 和 update.

　　　　_index(string) 操作对应的index名称，如果是data stream则是背后的具体index名称.

　　　　_type(string) 固定_doc.

　　　　_id(integer) 文档ID.

　　　　_version(integer) 文档最新版本.

　　　　result(string) 操作的结果. 成功的值有 created, deleted, 和updated. 该参数只有在成功时才返回。

　　　　_shards(object) 包含以下：

　　　　　　total(integer) 总的shard数量.

　　　　　　successful(integer) 成功的shard数量.

　　　　　　failed(integer) 失败的shard数量.

　　_seq_no(integer) 同上，该参数只有在成功时才返回。

　　_primary_term(integer) 同上，该参数只有在成功时才返回。

　　status(integer)操作的http code结果。

　　error(object) 该参数只有在失败时才返回，包含如下：

　　　　type(string) 操作的失败类型.

　　　　reason(string) 失败原因.

　　　　index_uuid(string) 失败的index的UUID.

　　　　shard(string) 失败的shard.

　　　　index(string) 失败对应的index名称，如果是data stream则是背后的具体index名称.

 

Reindex 把文档从source拷贝到target，source可以是index, alias, or data stream，target不能是自己；source的_source必须是enable的，target需要预先创建，不会拷贝source的settings到target。

POST /_reindex

简单例子

POST _reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}

 由于该API不常用，详细参考 Reindex 。