You're viewing version 2.17 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Rollover Index

Introduced 1.0

The Rollover Index API creates a new index for a data stream or index alias based on the wait_for_active_shards setting.

Path and HTTP methods

POST /<rollover-target>/_rollover/
POST /<rollover-target>/_rollover/<target-index>

Rollover types

You can roll over a data stream, an index alias with one index, or an index alias with a write index.

Data stream

When you perform a rollover operation on a data stream, the API generates a fresh write index for that stream. Simultaneously, the stream’s preceding write index transforms into a regular backing index. Additionally, the rollover process increments the generation count of the data stream. Data stream rollovers do not support specifying index settings in the request body.

Index alias with one index

When initiating a rollover on an index alias associated with a single index, the API generates a new index and disassociates the original index from the alias.

Index alias with a write index

When an index alias references multiple indexes, one index must be designated as the write index. During a rollover, the API creates a new write index with its is_write_index property set to true while updating the previous write index by setting its is_write_index property to false.

Incrementing index names for an alias

During the index alias rollover process, if you don’t specify a custom name and the current index’s name ends with a hyphen followed by a number (for example, my-index-000001 or my-index-3), then the rollover operation will automatically increment that number for the new index’s name. For instance, rolling over my-index-000001 will generate my-index-000002. The numeric portion is always padded with leading zeros to ensure a consistent length of six characters.

Using date math with index rollovers

When using an index alias for time-series data, you can leverage date math in the index name to track the rollover date. For example, you can create an alias pointing to my-index-{now/d}-000001. If you create an alias on June 11, 2029, then the index name would be my-index-2029.06.11-000001. For a rollover on June 12, 2029, the new index would be named my-index-2029.06.12-000002. See Roll over an index alias with a write index for a practical example.

Path parameters

The Rollover Index API supports the parameters listed in the following table.

Query parameters

The following table lists the supported query parameters.

Request body fields

The following request body fields are supported.

alias

The alias parameter specifies the alias name as the key. It is required when the template option exists in the request body. The object body contains the following optional parameters.

mappings

The mappings parameter specifies the index field mappings. It is optional. See Mappings and field types for more information.

conditions

The conditions parameter is an optional object defining criteria for triggering the rollover. When provided, OpenSearch only rolls over if the current index satisfies one or more specified conditions. If omitted, then the rollover occurs unconditionally without prerequisites.

The object body supports the following parameters.

settings

The settings parameter specifies the index configuration options. See Index settings for more information.

Example requests

The following examples illustrate using the Rollover Index API. A rollover occurs when one or more of the specified conditions are met:

• The index was created 5 or more days ago.
• The index contains 500 or more documents.
• The index’s largest primary shard is 100 GB or larger.

Rolling over a data stream

The following request rolls over the data stream if the current write index meets any of the specified conditions:

POST my-data-stream/_rollover
{
  "conditions": {
    "max_age": "5d",
    "max_docs": 500,
    "max_primary_shard_size": "100gb"
  }
}

Rolling over an index alias with a write index

The following request creates a date-time index and sets it as the write index for my-alias:

PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {
      "is_write_index": true
    }
  }
}

The next request performs a rollover using the alias:

POST my-alias/_rollover
{
  "conditions": {
    "max_age": "5d",
    "max_docs": 500,
    "max_primary_shard_size": "100gb"
  }
}

Specifying settings during a rollover

In most cases, you can use an index template to automatically configure the indexes created during a rollover operation. However, when rolling over an index alias, you can use the Rollover Index API to introduce additional index settings or override the settings defined in the template by sending the following request:

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

Example response

OpenSearch returns the following response confirming that all conditions except max_primary_shard_size were met:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-my-data-stream-2029.06.11-000001",
  "new_index": ".ds-my-data-stream-2029.06.12-000002",
  "rolled_over": true,
  "dry_run": false,
  "conditions": {
    "[max_age: 5d]": true,
    "[max_docs: 500]": true,
    "[max_primary_shard_size: 100gb]": false
  }
}