Rollover API

When you roll over an index alias, you can specify a name for the new index. If you don’t specify a name and the current index ends with - and a number, such as my-index-000001 or my-index-3, the new index name increments that number. For example, if you roll over an alias with a current index of my-index-000001, the rollover creates a new index named my-index-000002. This number is always 6 characters and zero-padded, regardless of the previous index’s name.

A rollover creates a new index and is subject to the wait_for_active_shards setting.

The following request rolls over a data stream unconditionally.

response = client.indices.rollover(
  alias: 'my-data-stream'
)
puts response

POST my-data-stream/_rollover

The following request only rolls over the data stream if the current write index meets one or more of the following conditions:

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"
  }
}

The API returns:

{
  "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,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

The following request creates <my-index-{now/d}-000001> and sets it as the write index for 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
    }
  }
}

The following request only rolls over the alias if the current write index meets one or more of the following conditions:

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"
  }
}

The API returns:

{
  "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,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

If the alias’s index names use date math and you roll over indices at a regular interval, you can use date math to narrow your searches. For example, the following search targets indices created in the last three days.

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

The following request creates <my-index-{now/d}-000001> and its alias, 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": { }
  }
}

The following request only rolls over the alias if the current index meets one or more of the following conditions:

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"
  }
}

The API returns:

{
  "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,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

Typically, you use an index template to automatically configure indices created during a rollover. If you roll over an index alias, you use the rollover API to add additional index settings or overwrite settings in the template. Data streams do not support the settings parameter.

response = client.indices.rollover(
  alias: 'my-alias',
  body: {
    settings: {
      'index.number_of_shards' => 2
    }
  }
)
puts response

POST my-alias/_rollover
{
  "settings": {
    "index.number_of_shards": 2
  }
}