Elasticsearch REST API 文档管理

原创

wx6375958b5f6b5 2023-12-29 09:50:06 ©著作权

文章标签 elasticsearch 创建文档索引重建索引版本控制 文章分类 Html/CSS 前端开发

©著作权归作者所有：来自51CTO博客作者wx6375958b5f6b5的原创作品，请联系作者获取转载授权，否则将追究法律责任

文章目录

创建文档

路径参数
常用查询参数
示例
响应说明

查询文档

路径参数编辑
查询参数
示例 1
响应说明
示例2
示例3

更新文档

路径参数
查询参数
示例1
示例2

禁用noop

mget 获取多个文档

路径参数
查询参数
请求正文参数说明
示例1
响应结果
示例2

删除文档

路径参数
查询参数
示例1 开放式并发控制更新或删除
响应结果
示例2：版本控制更新或删除
示例3：直接删除

索引重建

查询参数
请求正文
响应说明
先创建目标索引
示例：我们创建一个目标索引 person1
索引重建
响应信息

创建文档

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