OpenSearch/docs/reference/indices/rollover-index.asciidoc

[[indices-rollover-index]]
== Rollover Index

The rollover index API allows to switch the index pointed to by an alias given some predicates.
In order to rollover an index, the provided alias has to point to a single index. Upon satisfying
any of the predicates, the alias is switched to point to the rollover index, if the rollover index
already exists, the rollover fails.

This API is syntactic sugar for changing the index pointed to by an alias given some predicate.

The rollover API must be used against an alias that points to a single index:

[source,js]
--------------------------------------------------
$ curl -XPUT 'http://localhost:9200/index1' -d '{
    "aliases" : {
        "index_alias": {}
    }
}'
--------------------------------------------------

To rollover `index_alias` to point to a new index `index2`:

[source,js]
--------------------------------------------------
$ curl -XPOST 'http://localhost:9200/index_alias/_rollover/index2' -d '{
    "conditions" : {
        "max_age": "7d", <1>
        "max_docs": 1000 <2>
    }
}'
--------------------------------------------------
<1> Sets a condition that the index has to be at least 7 days old
<2> Sets a condition that the index has to have at least a 1000 documents

The API call above switches the index pointed to by `index_alias` from `index1` to `index2`, if any
of the conditions are met. `index2` is created (using matching <<indices-templates>> if available).
The API call returns immediately if none of the conditions are met.

The rollover API can be used without specifying the name for the new index. In this case, the API requires
the old concrete index name to have `{index_prefix}-{num}` format, as rollover index name is generated
following `{index_prefix}-{num+1}` format.

The `_rollover` API is similar to <<indices-create-index>> and accepts `settings`, `mappings` and
`aliases` to override the index create request for the rollover index.

[source,js]
--------------------------------------------------
$ curl -XPOST 'http://localhost:9200/index_alias/_rollover' -d '{
    "conditions" : {
        "max_age": "7d",
        "max_docs": 1000
    },
    "settings": { <1>
        "index.number_of_shards": 2
    }
}'
--------------------------------------------------
<1> Set settings to override matching index template, `mappings` and `aliases` can also be provided.

The rollover API supports `dry_run` mode, where request conditions can be checked without performing the
actual rollover. The `dry_run` mode can be enabled by setting `dry_run=true` as a request parameter.

An example response for the index rollover API:

[source,js]
--------------------------------------------------
{
	"old_index": "index-1", <1>
	"new_index": "index-2", <2>
	"rolled_over": true, <3>
	"dry_run": false, <4>
	"conditions": { <5>
	    "[max_age: 7d]": true,
	    "[max_docs: 1000]": true
	}
}
--------------------------------------------------
<1> name of the index the alias was pointing to
<2> name of the index the alias currently points to
<3> whether the alias switch was successful
<4> whether the rollover was dry run
<5> status of the evaluated request conditions