索引滚动（Rollover） #

Rollover API 用于在满足特定条件时，将一个别名或数据流（Data Stream）滚动到一个新的索引。这是管理时间序列数据的核心操作——让你的索引保持合理大小，避免单个索引无限膨胀。

基本用法 #

前置条件 #

Rollover 只能在以下两种目标上执行：

写入别名（Write Alias）：别名必须标记了 is_write_index: true
数据流（Data Stream）：天然支持 Rollover

对别名执行 Rollover #

先创建索引和写入别名：

PUT /logs-000001
{
  "aliases": {
    "logs-write": {
      "is_write_index": true
    }
  }
}

当条件满足时执行 Rollover：

POST /logs-write/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 10000000,
    "max_size": "50gb",
    "max_primary_shard_size": "25gb"
  }
}

响应：

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": "logs-000001",
  "new_index": "logs-000002",
  "rolled_over": true,
  "dry_run": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 10000000]": true,
    "[max_size: 50gb]": false,
    "[max_primary_shard_size: 25gb]": false
  }
}

任一条件满足即触发滚动。响应中会列出每个条件的评估结果。

对数据流执行 Rollover #

POST /logs-nginx/_rollover
{
  "conditions": {
    "max_age": "1d",
    "max_docs": 5000000
  }
}

指定新索引名 #

默认情况下，新索引名会在旧索引名基础上递增数字后缀（如 logs-000001 → logs-000002）。也可以指定自定义名称：

POST /logs-write/_rollover/logs-2024-07-01
{
  "conditions": {
    "max_age": "7d"
  }
}

滚动条件 #

条件	类型	说明
`max_age`	Time	索引创建后经过的时间（如 `"7d"`、`"30d"`）
`max_docs`	Long	索引中的文档总数
`max_size`	Size	索引的总大小（如 `"50gb"`）
`max_primary_shard_size`	Size	最大主分片的大小

max_primary_shard_size 是控制分片大小最实用的条件。推荐单个分片大小维持在 10–50GB 之间。

Dry Run：模拟执行 #

使用 dry_run 参数可以预览 Rollover 结果而不实际执行：

POST /logs-write/_rollover?dry_run
{
  "conditions": {
    "max_docs": 1000000
  }
}

为新索引指定设置 #

可以在请求体中为新索引指定设置、映射和别名：

POST /logs-write/_rollover
{
  "conditions": {
    "max_age": "7d"
  },
  "settings": {
    "index.number_of_shards": 3,
    "index.number_of_replicas": 1
  },
  "mappings": {
    "properties": {
      "message": { "type": "text" }
    }
  },
  "aliases": {
    "logs-read": {}
  }
}

通常建议使用索引模板来统一管理新索引的设置和映射，而不是在每次 Rollover 时手动指定。

查询参数 #

参数	类型	默认值	说明
`dry_run`	Boolean	`false`	模拟执行，不实际创建新索引
`timeout`	Time	`30s`	操作超时时间
`master_timeout`	Time	`30s`	连接主节点的超时时间
`wait_for_active_shards`	String	—	等待的活跃分片数

索引命名约定 #

要让自动递增的数字后缀生效，索引名必须以 - 和数字结尾，且数字需要足够的前导零：

当前索引	Rollover 后
`logs-000001`	`logs-000002`
`logs-2024-01-000001`	`logs-2024-01-000002`
`my-index-3`	`my-index-000004`

建议统一使用 6 位数字后缀（如 -000001），为未来的滚动留出足够空间。

与 ILM 配合使用 #

在生产环境中，通常不手动调用 Rollover API，而是通过索引生命周期管理（ILM）策略自动触发 Rollover。ILM 会定期检查条件，满足时自动执行滚动。

典型的 ILM + Rollover 流程：

定义 ILM 策略，在 hot 阶段设置 Rollover 条件
创建索引模板，关联 ILM 策略
创建初始索引和写入别名
ILM 自动管理后续的滚动、迁移和删除

下一步 #

索引模板：为 Rollover 创建的新索引预配设置
别名（Aliases）：写入别名的管理
数据流：天然支持 Rollover 的时序数据管理
索引生命周期管理：自动化 Rollover 策略