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

  1. POST /<rollover-target>/_rollover/
  2. 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.

ParameterTypeDescription
<rollover-target>StringThe name of the data stream or index alias to roll over. Required.
<target-index>StringThe name of the index to create. Supports date math. Data streams do not support this parameter. If the name of the alias’s current write index does not end with - and a number, such as my-index-000001 or my-index-2, then the parameter is required.

Query parameters

The following table lists the supported query parameters.

ParameterTypeDescription
cluster_manager_timeoutTimeThe amount of time to wait for a connection to the cluster manager node. Default is 30s.
timeoutTimeThe amount of time to wait for a response. Default is 30s.
wait_for_active_shardsStringThe number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). You can also set to all or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, then the index must have two replicas distributed across two additional nodes in order for the operation to succeed.

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.

ParameterTypeDescription
filterQuery DSL objectThe query that limits the number of documents that the alias can access.
index_routingStringThe value that routes indexing operations to a specific shard. When specified, overwrites the routing value for indexing operations.
is_hiddenBooleanHides or unhides the alias. When true, the alias is hidden. Default is false. Indexes for the alias must have matching values for this setting.
is_write_indexBooleanSpecifies the write index. When true, the index is the write index for the alias. Default is false.
routingStringThe value used to route index and search operations to a specific shard.
search_routingStringRoutes search operations to a specific shard. When specified, it overwrites routing for search operations.

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.

ParameterTypeDescription 
 max_ageTime unitsTriggers a rollover after the maximum elapsed time since index creation is reached. The elapsed time is always calculated since the index creation time, even if the index origination date is configured to a custom date, such as when using the index.lifecycle.parse_origination_date or index.lifecycle.origination_date settings. Optional.
max_docsIntegerTriggers a rollover after the specified maximum number of documents, excluding documents added since the last refresh and documents in replica shards. Optional. 
max_sizeByte unitsTriggers a rollover when the index reaches a specified size, calculated as the total size of all primary shards. Replicas are not counted. Use the _cat indices API and check the pri.store.size value to see the current index size. Optional. 
max_primary_shard_sizeByte unitsTriggers a rollover when the largest primary shard in the index reaches a certain size. This is the maximum size of the primary shards in the index. As with max_size, replicas are ignored. To see the current shard size, use the _cat shards API. The store value shows the size of each shard, and prirep indicates whether a shard is a primary (p) or a replica (r). Optional. 

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:

  1. POST my-data-stream/_rollover
  2. {
  3. "conditions": {
  4. "max_age": "5d",
  5. "max_docs": 500,
  6. "max_primary_shard_size": "100gb"
  7. }
  8. }

copy

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:

  1. PUT <my-index-{now/d}-000001>
  2. PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
  3. {
  4. "aliases": {
  5. "my-alias": {
  6. "is_write_index": true
  7. }
  8. }
  9. }

copy

The next request performs a rollover using the alias:

  1. POST my-alias/_rollover
  2. {
  3. "conditions": {
  4. "max_age": "5d",
  5. "max_docs": 500,
  6. "max_primary_shard_size": "100gb"
  7. }
  8. }

copy

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:

  1. POST my-alias/_rollover
  2. {
  3. "settings": {
  4. "index.number_of_shards": 4
  5. }
  6. }

copy

Example response

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

  1. {
  2. "acknowledged": true,
  3. "shards_acknowledged": true,
  4. "old_index": ".ds-my-data-stream-2029.06.11-000001",
  5. "new_index": ".ds-my-data-stream-2029.06.12-000002",
  6. "rolled_over": true,
  7. "dry_run": false,
  8. "conditions": {
  9. "[max_age: 5d]": true,
  10. "[max_docs: 500]": true,
  11. "[max_primary_shard_size: 100gb]": false
  12. }
  13. }