3.4.2.13.Rollover API

创作人：杨松柏

了解 Elasticsearch 的同学应该都知道，索引的主分片在设定之后，改变（shrink ，split，

reindex）主分片数目的成本相当大；因此在设计之初，一定要规划好索引的分片数目。如果集群的中节点数目固定，且写入的数据不会再有更新操作或者更新操作极其少；可以使用Rollover index的方式来限制每个索引的大小。

Rollover：

若rollover-target绑定的当前索引满足设定的条件，执行滚动操作将会为rollover-target创建新索引。滚动目标可以是索引别名或者数据流；

l 当滚动目标是别名时，执行滚动别名将指向新的索引。

l 当滚动目标是数据流时，数据流将数据写入到新的索引，且新索引名后缀自增 1。

POST /alias1/_rollover/my-index-000002
{
  "conditions": {
    "max_age":   "7d",
    "max_docs":  2,
    "max_size": "5gb"
  }
}

如果需要实现 Rollover 自动化，可以自行实现一个定时任务请求该 API 或者使用 Elasticsearch 的 index lifecycle management (ILM) 功能。

API 介绍

Rollover API

POST /<rollover-target>/_rollover/<target-index>?wait_for_active_shards=<number>
POST /<rollover-target>/_rollover?wait_for_active_shards=<number>

URI 参数

必填参数，参数类型string。将已存的索引别名或数据流，分配给目标索引，来完成执行滚动。

可选参数，参数类型string。代表要被创建和分配索引别名的目标索引名称；

目标索引名称必须遵循以下规则：

l 所有字符必须小写

l 不允许包含\， /， *， ?， "， <， >，|， ` ` (space character)， ,， #

l 在7.0版本之前允许包含：，在7.0+不再支持

l 不能够以-，_，+开头

l 名称不能够是.或者..

l 长度不能超过 255 字节(注意：这是字节数限制，如果是字符得看表示一个字符需要多少个字节)

l 名称以 . 开头已经过时；除了隐藏索引和由插件管理的内部索引

如果rollover-target为数据流， 参数是不被允许的；执行 Rollover 数据流会按照相应规则生产新的索引：格式为 .ds--000001，其中-000001，数字必为6位数，左侧高位用0 补充，每发生一次 Rollover 自增加1。

 如果rollover-target为一个索引别名，且别名绑定的索引以 - 结尾；如果不指定

 执行 Rollover ，将生成新的索引indexName-+1。

如果别名现绑定的索引名称不满足以 - 形式结尾，则必须指定 。

查询参数

dry_run

可选参数，参数类型为boolean，默认值为 false。该参数的作用为检测 index 是否满足提供的 rollover 条件。 如果设置为true，将会完成检查工作，但不会真正执行 rollover 。

include_type_name

可选参数，参数类型为boolean，默认值为 false。在 mappings体内要求必须有mapping

type。

wait_for_active_shards

可选参数，参数类型为 string，默认值为 1（即只要一个主分片处于活跃便可以执行操作）。在执行rollover,要求处于活跃状态的索引分片副本数目，以保证数据的可靠和安全性；设置为

all或任何正整数，最多为索引分片的总数（number_of_replicas+1）。

详情可以参考 Active shards：https://www.elastic.co/guide/en/elasticsearch/reference/7.10/docs-index_.html#index-wait-for-active-shards

master_timeout

可选参数，value值的单位可为d、h、m、s、ms、micros、nanos，默认值为30s。等待连接到主节点的时间。如果在超时时间阈值之前没有收到响应，则请求失败并返回错误。

timeout

可选参数，value 值的单位可为d、h、m、s、ms、micros、nanos，默认值为30s。请求等待

响应的时间。如果在超时时间阈值之前没有收到响应，则请求失败并返回错误。

请求体参数

aliases

可选参数，alias object。包含索引的 Index aliases。详情可以参看索引别名，批量操作的相关内容（即_aliases API）。

conditions

可选参数,参数类型object。如果设置条件，则只有现有索引达到条件集任何一个条件的阈值才会完成rollover。如果省略，则无条件执行rollover。条件集包括：

l max_age

l 可选参数，value 值的单位可为d、h、m、s、ms、micros、nanos；依据索引的创建时间与现在时间差值作为阈值。

l max_docs

l 可选参数，参数类型为integer；索引的最大文档数目；计数不包括自上次refresh之后新添加的文档和副本分片的文档。

l max_size

l 可选参数， byte units 值（单位b、kb、mb、gb、tb、pb）。索引大小的最大值，只计算索引主分片的大小，副本不包括在内。

 mappings

可选参数，参数 mapping object。为索引进行数据建模，定义字段schema等。如果设置，mapping可能包含：

l 字段名字（Field names）

l 字段的数据类型（Field data types）

l mapping中一些修饰参数（Mapping parameters）

settings

可选参数，参数 index setting object。索引的配置选项；比如设置滚动产生的新索引副本分片数目等等。

详情可以参看 Index Settings：https://www.elastic.co/guide/en/elasticsearch/reference/7.10/index-modules.html#index-modules-settings

《Elastic Stack 实战手册》——三、产品能力——3.4.入门篇——3.4.2.Elasticsearch基础应用——3.4.2.13.Rollover API（2） https://developer.aliyun.com/article/1230208