Rollover index API

Because the rollover operation creates a new index to rollover to, the wait_for_active_shards setting on index creation applies to the rollover action.

PUT /logs-000001 
{
  "aliases": {
    "logs_write": {}
  }
}

# Add > 1000 documents to logs-000001

POST /logs_write/_rollover 
{
  "conditions": {
    "max_age":   "7d",
    "max_docs":  1000,
    "max_size":  "5gb"
  }
}

The API returns the following response:

{
  "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: 1000]": true,
    "[max_size: 5gb]": false,
  }
}

The settings, mappings, and aliases for the new index are taken from any matching index templates. Additionally, you can specify settings, mappings, and aliases in the body of the request, just like the create index API. Values specified in the request override any values set in matching index templates. For example, the following rollover request overrides the index.number_of_shards setting:

PUT /logs-000001
{
  "aliases": {
    "logs_write": {}
  }
}

POST /logs_write/_rollover
{
  "conditions" : {
    "max_age": "7d",
    "max_docs": 1000,
    "max_size": "5gb"
  },
  "settings": {
    "index.number_of_shards": 2
  }
}

If the name of the existing index ends with - and a number — e.g. logs-000001 — then the name of the new index will follow the same pattern, incrementing the number (logs-000002). The number is zero-padded with a length of 6, regardless of the old index name.

If the old name doesn’t match this pattern then you must specify the name for the new index as follows:

POST /my_alias/_rollover/my_new_index_name
{
  "conditions": {
    "max_age":   "7d",
    "max_docs":  1000,
    "max_size": "5gb"
  }
}

It can be useful to use date math to name the rollover index according to the date that the index rolled over, e.g. logstash-2016.02.03. The rollover API supports date math, but requires the index name to end with a dash followed by a number, e.g. logstash-2016.02.03-1 which is incremented every time the index is rolled over. For instance:

# PUT /<logs-{now/d}-1> with URI encoding:
PUT /%3Clogs-%7Bnow%2Fd%7D-1%3E 
{
  "aliases": {
    "logs_write": {}
  }
}

PUT logs_write/_doc/1
{
  "message": "a dummy log"
}

POST logs_write/_refresh

# Wait for a day to pass

POST /logs_write/_rollover 
{
  "conditions": {
    "max_docs":   "1"
  }
}

These indices can then be referenced as described in the date math documentation. For example, to search over indices created in the last three days, you could do the following:

# GET /<logs-{now/d}-*>,<logs-{now/d-1d}-*>,<logs-{now/d-2d}-*>/_search
GET /%3Clogs-%7Bnow%2Fd%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-1d%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-2d%7D-*%3E/_search

The rollover API supports dry_run mode, where request conditions can be checked without performing the actual rollover.

POST /logs_write/_rollover?dry_run
{
  "conditions" : {
    "max_age": "7d",
    "max_docs": 1000,
    "max_size": "5gb"
  }
}

The rollover alias when rolling over a write index that has is_write_index explicitly set to true is not swapped during rollover actions. Since having an alias point to multiple indices is ambiguous in distinguishing which is the correct write index to roll over, it is not valid to rollover an alias that points to multiple indices. For this reason, the default behavior is to swap which index is being pointed to by the write-oriented alias. This was logs_write in some of the above examples. Since setting is_write_index enables an alias to point to multiple indices while also being explicit as to which is the write index that rollover should target, removing the alias from the rolled over index is not necessary. This simplifies things by allowing for one alias to behave both as the write and read aliases for indices that are being managed with Rollover.

Look at the behavior of the aliases in the following example where is_write_index is set on the rolled over index.

PUT my_logs_index-000001
{
  "aliases": {
    "logs": { "is_write_index": true } 
  }
}

PUT logs/_doc/1
{
  "message": "a dummy log"
}

POST logs/_refresh

POST /logs/_rollover
{
  "conditions": {
    "max_docs":   "1"
  }
}

PUT logs/_doc/2 
{
  "message": "a newer log"
}

{
  "_index" : "my_logs_index-000002",
  "_type" : "_doc",
  "_id" : "2",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

After the rollover, the alias metadata for the two indices will have the is_write_index setting reflect each index’s role, with the newly created index as the write index.

{
  "my_logs_index-000002": {
    "aliases": {
      "logs": { "is_write_index": true }
    }
  },
  "my_logs_index-000001": {
    "aliases": {
      "logs": { "is_write_index" : false }
    }
  }
}