How to Rollover Index in Elasticsearch: Syntax and Example

To rollover an index in Elasticsearch, use the _rollover API on an alias pointing to the current write index. This creates a new index when conditions like max age or max size are met, allowing seamless index management without downtime.

Syntax

The rollover API syntax requires specifying the alias that points to the current write index and optional conditions to trigger the rollover.

• POST /<alias>/_rollover: The HTTP method and endpoint where <alias> is the alias name.
• conditions: JSON object defining when to rollover, such as max_age, max_docs, or max_size.
• settings (optional): New index settings for the rolled-over index.
• mappings (optional): New index mappings for the rolled-over index.

json

POST /my-index-alias/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000
  },
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "field1": { "type": "text" }
    }
  }
}

Example

This example shows how to rollover an index alias logs-write when the index is older than 1 day or has more than 5000 documents. It also sets the number of shards for the new index.

json

POST /logs-write/_rollover
{
  "conditions": {
    "max_age": "1d",
    "max_docs": 5000
  },
  "settings": {
    "number_of_shards": 2
  }
}

Output

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": "logs-000001",
  "new_index": "logs-000002",
  "rolled_over": true,
  "conditions": {
    "max_age": true,
    "max_docs": false
  }
}

Common Pitfalls

• Alias not pointing to a write index: The rollover API requires the alias to point to a single write index. If it points to multiple or no indices, rollover fails.
• Missing conditions: Without conditions, rollover always creates a new index, which may be unintended.
• Incorrect alias setup: Forgetting to set the alias as a write alias on the current index causes errors.

json

POST /logs-write/_rollover
{
  "settings": {
    "number_of_shards": 1
  }
}

-- Wrong: No conditions, rollover always triggers

POST /logs-write/_rollover
{
  "conditions": {
    "max_docs": 10000
  }
}

-- Right: Rollover only if docs exceed 10000

Quick Reference

Parameter	Description	Example
alias	Name of the alias pointing to the current write index	logs-write
conditions	Rules to trigger rollover like max_age, max_docs, max_size	{"max_age": "7d", "max_docs": 1000}
settings	Settings for the new index after rollover	{"number_of_shards": 1}
mappings	Mappings for the new index	{"properties": {"field1": {"type": "text"}}}

Key Takeaways

Use the rollover API on an alias that points to the current write index to create new indices automatically.

Define rollover conditions like max_age, max_docs, or max_size to control when rollover happens.

Ensure the alias is correctly set as a write alias to avoid errors.

Without conditions, rollover will always create a new index, which may cause unnecessary index creation.

You can specify new index settings and mappings during rollover for better control.