滚动 API
编辑滚动 API编辑
response = client.indices.rollover( alias: 'my-data-stream' ) puts response
POST my-data-stream/_rollover
描述编辑
滚动 API 为数据流或索引别名创建一个新的索引。API 的行为取决于滚动目标。
滚动数据流
如果您滚动数据流，API 将为该流创建一个新的写入索引。该流的先前写入索引将成为一个常规的备份索引。滚动还会增加数据流的代数。请参阅 滚动。
滚动具有写入索引的索引别名
在 Elasticsearch 7.9 之前，您通常会使用 具有写入索引的索引别名 来管理时间序列数据。数据流取代了此功能，需要更少的维护，并自动与 数据层 集成。
请参阅 将索引别名转换为数据流。
如果索引别名指向多个索引，则其中一个索引必须是 写入索引。滚动 API 为别名创建一个新的写入索引，并将 is_write_index 设置为 true。API 还将先前写入索引的 is_write_index 设置为 false。
滚动只有一个索引的索引别名
如果您滚动指向单个索引的索引别名，API 将为该别名创建一个新的索引，并从该别名中删除原始索引。
为别名递增索引名称编辑
当您滚动索引别名时，您可以为新索引指定一个名称。如果您没有指定名称，并且当前索引以 - 和一个数字结尾，例如 my-index-000001 或 my-index-3，则新索引名称将递增该数字。例如，如果您滚动一个当前索引为 my-index-000001 的别名，则滚动将创建一个名为 my-index-000002 的新索引。无论先前索引的名称如何，此数字始终为 6 个字符，并用零填充。
等待活动分片编辑
滚动会创建一个新的索引，并且会受到 wait_for_active_shards 设置的影响。
路径参数编辑
-
<rollover-target> - (必需，字符串) 要滚动的索引别名或数据流的名称。
-
<target-index> -
(可选，字符串) 要创建的索引的名称。支持 日期数学。数据流不支持此参数。
如果别名的当前写入索引的名称不以
-和一个数字结尾，例如my-index-000001或my-index-3，则此参数是必需的。索引名称必须符合以下条件
- 仅限小写
- 不能包含
\、/、*、?、"、<、>、|、` `（空格字符）、,、# - 7.0 之前的索引可以包含冒号 (
:)，但这已弃用，在 7.0+ 中将不再支持 - 不能以
-、_、+开头 - 不能是
.或.. - 不能超过 255 个字节（注意是字节，因此多字节字符将更快地达到 255 个字节的限制）
- 以
.开头的名称已弃用，但 隐藏索引 和插件管理的内部索引除外
查询参数编辑
-
dry_run - (可选，布尔值) 如果为
true，则检查当前索引是否满足指定的conditions，但不执行滚动。默认为false。 -
lazy - (可选，布尔值) 如果为
true，则表示将在下次索引操作发生时滚动数据流。仅适用于数据流。默认为false。 -
wait_for_active_shards -
(可选，字符串) 在继续操作之前必须处于活动状态的分片副本数量。设置为
all或任何正整数，直到索引中的分片总数 (number_of_replicas+1)。默认值：1，主分片。请参阅 活动分片。
-
master_timeout - (可选，时间单位) 等待主节点的时长。如果在超时时间到期之前主节点不可用，则请求将失败并返回错误。默认为
30s。也可以设置为-1，表示请求永远不会超时。 -
timeout - (可选，时间单位) 等待响应的时长。如果在超时时间到期之前未收到响应，则请求将失败并返回错误。默认为
30s。
请求正文编辑
-
aliases -
(可选，对象的对象) 目标索引的别名。数据流不支持此参数。
aliases对象的属性-
<alias> -
(必需，对象) 键是别名名称。索引别名名称支持 日期数学。
对象正文包含别名的选项。支持空对象。
<alias>的属性-
filter - (可选，查询 DSL 对象) 用于限制别名可以访问的文档的查询。
-
index_routing - (可选，字符串) 用于将索引操作路由到特定分片的 value。如果指定，则会覆盖索引操作的
routingvalue。 -
is_hidden - (可选，布尔值) 如果为
true，则别名是 隐藏的。默认为false。别名的所有索引都必须具有相同的is_hiddenvalue。 -
is_write_index - (可选，布尔值) 如果为
true，则该索引是别名的 写入索引。默认为false。 -
routing - (可选，字符串) 用于将索引和搜索操作路由到特定分片的 value。
-
search_routing - (可选，字符串) 用于将搜索操作路由到特定分片的 value。如果指定，则会覆盖搜索操作的
routingvalue。
-
-
-
conditions -
(可选，对象) 滚动的条件。如果指定，则 Elasticsearch 仅在当前索引满足这些条件时才执行滚动。如果未指定此参数，则 Elasticsearch 将无条件地执行滚动。
如果指定了条件，则其中至少一个必须是 max_* 条件。如果满足任何 max_* 条件，并且所有 min_* 条件都满足，则索引将滚动。
要触发滚动，当前索引必须在请求时满足这些条件。Elasticsearch 不会在 API 响应后监控索引。要自动执行滚动，请使用 ILM 的
rollover代替。conditions的属性-
max_age - (可选，时间单位) 在索引创建后达到最大经过时间时触发滚动。经过时间始终从索引创建时间开始计算，即使索引起始日期配置为自定义日期，例如使用 index.lifecycle.parse_origination_date 或 index.lifecycle.origination_date 设置。
-
max_docs - (可选，整数) 在达到指定的最大文档数后触发滚动。自上次刷新以来添加的文档不包含在文档计数中。文档计数不包括副本分片中的文档。
-
max_size -
(可选，字节大小单位) 当索引达到一定大小后触发滚动。这是索引中所有主分片的总大小。副本不计入最大索引大小。
要查看当前索引大小，请使用 _cat indices API。
pri.store.size值显示所有主分片的组合大小。 -
max_primary_shard_size -
(可选，字节大小单位) 当索引中最大的主分片达到一定大小后触发滚动。这是索引中主分片的最大大小。与
max_size一样，副本被忽略。要查看当前分片大小，请使用 _cat shards API。
store值显示每个分片的大小，而prirep指示分片是主分片 (p) 还是副本分片 (r)。 -
max_primary_shard_docs -
(可选，整数) 当索引中最大的主分片达到一定数量的文档后触发滚动。这是索引中主分片的最大文档数。与
max_docs一样，副本被忽略。要查看当前分片文档，请使用 _cat shards API。
docs值显示每个分片中的文档数量。 -
min_age - (可选，时间单位) 在达到索引创建后的最小经过时间之前阻止滚动。请参阅有关
max_age的说明。 -
min_docs - (可选，整数) 在达到指定的最少文档数之前阻止滚动。请参阅有关
max_docs的说明。 -
min_size - (可选，字节大小单位) 在索引达到一定大小之前阻止滚动。请参阅有关
max_size的说明。 -
min_primary_shard_size - (可选，字节大小单位) 在索引中最大的主分片达到一定大小之前阻止滚动。请参阅有关
max_primary_shard_size的说明。 -
min_primary_shard_docs - (可选，整数) 在索引中最大的主分片达到一定数量的文档之前阻止滚动。请参阅有关
max_primary_shard_docs的说明。
-
-
mappings -
(可选，映射对象) 索引中字段的映射。如果指定，此映射可以包含
请参阅 映射。
数据流不支持此参数。
-
settings -
数据流不支持此参数。
响应主体edit
-
acknowledged - (布尔值) 如果为
true，则请求在timeout周期内从主节点收到响应。 -
shards_acknowledged - (布尔值) 如果为
true，则请求在master_timeout周期内从 活动分片 收到响应。 -
old_index - (字符串) 数据流或索引别名的先前索引。对于具有写入索引的数据流和索引别名，这是先前写入索引。
-
new_index - (字符串) 由滚动创建的索引。对于具有写入索引的数据流和索引别名，这是当前写入索引。
-
rolled_over - (布尔值) 如果为
true，则数据流或索引别名已滚动。 -
dry_run - (布尔值) 如果为
true，则 Elasticsearch 未执行滚动。 -
condition -
(对象) 请求的
conditions中指定的每个条件的结果。如果未指定任何条件，则这是一个空对象。condition的属性-
<condition> - (布尔值) 键是每个条件。值为其结果。如果为
true，则索引满足条件。
-
-
lazy - (布尔值) 如果为
true，则 Elasticsearch 未执行滚动，但成功地将数据流标记为在下一个索引事件时滚动。
示例edit
滚动数据流edit
以下请求无条件地滚动数据流。
response = client.indices.rollover( alias: 'my-data-stream' ) puts response
POST my-data-stream/_rollover
以下请求延迟滚动数据流，这意味着数据流将在下一个索引事件时滚动。这确保了映射和设置更改将应用于即将到来的数据，但它将避免为摄取速度慢的数据流创建额外的支持索引。
POST my-data-stream/_rollover?lazy
以下请求仅在当前写入索引满足以下一个或多个条件时才滚动数据流
- 索引是在 7 天或更久之前创建的。
- 索引包含 1,000 个或更多文档。
- 索引的最大主分片大小为 50GB 或更大。
response = client.indices.rollover(
alias: 'my-data-stream',
body: {
conditions: {
max_age: '7d',
max_docs: 1000,
max_primary_shard_size: '50gb',
max_primary_shard_docs: '2000'
}
}
)
puts response
POST my-data-stream/_rollover
{
"conditions": {
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
}
}
API 返回
{
"acknowledged": true,
"shards_acknowledged": true,
"old_index": ".ds-my-data-stream-2099.05.06-000001",
"new_index": ".ds-my-data-stream-2099.05.07-000002",
"rolled_over": true,
"dry_run": false,
"lazy": false,
"conditions": {
"[max_age: 7d]": false,
"[max_docs: 1000]": true,
"[max_primary_shard_size: 50gb]": false,
"[max_primary_shard_docs: 2000]": false
}
}
滚动具有写入索引的索引别名edit
以下请求创建 <my-index-{now/d}-000001> 并将其设置为 my-alias 的写入索引。
response = client.indices.create(
index: '<my-index-{now/d}-000001>',
body: {
aliases: {
"my-alias": {
is_write_index: true
}
}
}
)
puts response
# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
"aliases": {
"my-alias": {
"is_write_index": true
}
}
}
以下请求仅在当前写入索引满足以下一个或多个条件时才滚动别名
- 索引是在 7 天或更久之前创建的。
- 索引包含 1,000 个或更多文档。
- 索引的最大主分片大小为 50GB 或更大。
response = client.indices.rollover(
alias: 'my-alias',
body: {
conditions: {
max_age: '7d',
max_docs: 1000,
max_primary_shard_size: '50gb',
max_primary_shard_docs: '2000'
}
}
)
puts response
POST my-alias/_rollover
{
"conditions": {
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
}
}
API 返回
{
"acknowledged": true,
"shards_acknowledged": true,
"old_index": "my-index-2099.05.06-000001",
"new_index": "my-index-2099.05.07-000002",
"rolled_over": true,
"dry_run": false,
"lazy": false,
"conditions": {
"[max_age: 7d]": false,
"[max_docs: 1000]": true,
"[max_primary_shard_size: 50gb]": false,
"[max_primary_shard_docs: 2000]": false
}
}
如果别名的索引名称使用日期数学，并且您定期滚动索引，则可以使用日期数学来缩小搜索范围。例如，以下搜索针对过去三天创建的索引。
response = client.search(
index: '<my-index-{now/d}-*>,<my-index-{now/d-1d}-*>,<my-index-{now/d-2d}-*>'
)
puts response
# GET /<my-index-{now/d}-*>,<my-index-{now/d-1d}-*>,<my-index-{now/d-2d}-*>/_search
GET /%3Cmy-index-%7Bnow%2Fd%7D-*%3E%2C%3Cmy-index-%7Bnow%2Fd-1d%7D-*%3E%2C%3Cmy-index-%7Bnow%2Fd-2d%7D-*%3E/_search
滚动具有一个索引的索引别名edit
以下请求创建 <my-index-{now/d}-000001> 及其别名 my-write-alias。
response = client.indices.create(
index: '<my-index-{now/d}-000001>',
body: {
aliases: {
"my-write-alias": {}
}
}
)
puts response
# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
"aliases": {
"my-write-alias": { }
}
}
以下请求仅在当前索引满足以下一个或多个条件时才滚动别名
- 索引是在 7 天或更久之前创建的。
- 索引包含 1,000 个或更多文档。
- 索引的最大主分片大小为 50GB 或更大。
response = client.indices.rollover(
alias: 'my-write-alias',
body: {
conditions: {
max_age: '7d',
max_docs: 1000,
max_primary_shard_size: '50gb',
max_primary_shard_docs: '2000'
}
}
)
puts response
POST my-write-alias/_rollover
{
"conditions": {
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
}
}
API 返回
{
"acknowledged": true,
"shards_acknowledged": true,
"old_index": "my-index-2099.05.06-000001",
"new_index": "my-index-2099.05.07-000002",
"rolled_over": true,
"dry_run": false,
"lazy": false,
"conditions": {
"[max_age: 7d]": false,
"[max_docs: 1000]": true,
"[max_primary_shard_size: 50gb]": false,
"[max_primary_shard_docs: 2000]": false
}
}