[[indices-rollover-index]]
=== Rollover API
++++
<titleabbrev>Rollover</titleabbrev>
++++

Creates a new index for a <<data-streams,data stream>> or <<aliases,index alias>>.

[source,console]
----
POST my-data-stream/_rollover
----
// TEST[setup:my_data_stream]
// TEST[teardown:data_stream_cleanup]

[[rollover-index-api-request]]
==== {api-request-title}

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

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

[[rollover-index-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-indices,index privilege>> for the rollover target.

[[rollover-index-api-desc]]
==== {api-description-title}

TIP: We recommend using {ilm-init}'s <<ilm-rollover,`rollover`>> action to
automate rollovers. See <<ilm-index-lifecycle>>.

The rollover API creates a new index for a data stream or index alias.
The API's behavior depends on the rollover target.

**Roll over a data stream**

If you roll over a data stream, the API creates a new write index for the
stream. The stream's previous write index becomes a regular backing index. A
rollover also increments the data stream's generation. See
<<data-streams-rollover>>.

**Roll over an index alias with a write index**

[TIP]
====
include::{es-ref-dir}/data-streams/set-up-a-data-stream.asciidoc[tag=time-series-alias-tip]
See <<convert-index-alias-to-data-stream>>.
====

If an index alias points to multiple indices, one of the indices must be a
<<write-index,write index>>. The rollover API creates a new write index
for the alias with `is_write_index` set to `true`. The API also sets
`is_write_index` to `false` for the previous write index.

**Roll over an index alias with one index**

If you roll over an index alias that points to only one index, the API creates a
new index for the alias and removes the original index from the alias.

[[increment-index-names-for-alias]]
===== Increment index names for an alias

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.

[[_using_date_math_with_the_rollover_api]]
.Use date math with index alias rollovers
****
If you use an index alias for time series data, you can use
<<api-date-math-index-names,date math>> in the index name to track the rollover
date. For example, you can create an alias that points to an index named
`<my-index-{now/d}-000001>`. If you create the index on May 6, 2099, the index's
name is `my-index-2099.05.06-000001`. If you roll over the alias on May 7, 2099,
the new index's name is `my-index-2099.05.07-000002`. For an example, see
<<roll-over-index-alias-with-write-index>>.
****

[[rollover-wait-active-shards]]
===== Wait for active shards

A rollover creates a new index and is subject to the
<<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting.

[[rollover-index-api-path-params]]
==== {api-path-parms-title}

`<rollover-target>`::
(Required, string)
Name of the data stream or index alias to roll over.

`<target-index>`::
(Optional, string)
Name of the index to create. Supports <<api-date-math-index-names,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-3`, this parameter is required.
+
include::{es-ref-dir}/indices/create-index.asciidoc[tag=index-name-reqs]

[[rollover-index-api-query-params]]
==== {api-query-parms-title}

`dry_run`::
(Optional, Boolean)
If `true`, checks whether the current index satisfies the specified
`conditions` but does not perform a rollover. Defaults to `false`.

`lazy`::
(Optional, Boolean)
If `true`, signals that the data stream will be rolled over when the next
indexing operation occurs. Applies only to data streams. Defaults to `false`.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

[role="child_attributes"]
[[rollover-index-api-request-body]]
==== {api-request-body-title}

`aliases`::
(Optional, object of objects) Aliases for the target index. Data streams do not
support this parameter.
+
include::{es-ref-dir}/indices/create-index.asciidoc[tag=aliases-props]

[[rollover-conditions]]
`conditions`::
(Optional, object)
Conditions for the rollover. If specified, {es} only performs the rollover if
the current index satisfies these conditions. If this parameter is
not specified, {es} performs the rollover unconditionally.
+
If conditions are specified, at least one of them must be a max_* condition.
The index will rollover if any max_* condition is satisfied and all
min_* conditions are satisfied.
+
IMPORTANT: To trigger a rollover, the current index must satisfy these conditions
at the time of the request. {es} does not monitor the index after the API
response. To automate rollover, use {ilm-init}'s <<ilm-rollover,`rollover`>>
instead.
+
.Properties of `conditions`
[%collapsible%open]
====
include::{es-ref-dir}/ilm/actions/ilm-rollover.asciidoc[tag=rollover-conditions]
====

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]
+
Data streams do not support this parameter.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
+
Data streams do not support this parameter.

[role="child_attributes"]
[[rollover-index-api-response-body]]
==== {api-response-body-title}

`acknowledged`::
(Boolean)
If `true`, the request received a response from the master node within the
`timeout` period.

`shards_acknowledged`::
(Boolean)
If `true`, the request received a response from
<<index-wait-for-active-shards,active shards>> within the `master_timeout`
period.

`old_index`::
(string)
Previous index for the data stream or index alias. For data streams and index
aliases with a write index, this is the previous write index.

`new_index`::
(string)
Index created by the rollover. For data streams and index aliases with a write
index, this is the current write index.

`rolled_over`::
(Boolean)
If `true`, the data stream or index alias rolled over.

`dry_run`::
(Boolean)
If `true`, {es} did not perform the rollover.

`condition`::
(object)
Result of each condition specified in the request's `conditions`. If no
conditions were specified, this is an empty object.
+
.Properties of `condition`
[%collapsible%open]
====
`<condition>`::
(Boolean) The key is each condition. The value is its result. If `true`, the
index met the condition.
====

`lazy`::
(Boolean)
If `true`, {es} did not perform the rollover, but successfully marked the data stream to be rolled
over at the next indexing event.

[[rollover-index-api-example]]
==== {api-examples-title}

[[roll-over-data-stream]]
===== Roll over a data stream

The following request rolls over a data stream unconditionally.

[source,console]
----
POST my-data-stream/_rollover
----
// TEST[setup:my_data_stream]

The following request rolls over a data stream lazily, meaning that the data stream
will roll over at the next indexing event. This ensures that mapping and setting changes
will be applied to the coming data, but it will avoid creating extra backing indices for
data streams with slow ingestion.

[source,console]
----
POST my-data-stream/_rollover?lazy
----
// TEST[continued]

:target: data stream
:index: write index

// tag::rollover-conditions-ex[]
The following request only rolls over the {target} if the current {index}
meets one or more of the following conditions:

* The index was created 7 or more days ago.
* The index contains 1,000 or more documents.
* The index's largest primary shard is 50GB or larger.
// end::rollover-conditions-ex[]

[source,console]
----
POST my-data-stream/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}
----
// TEST[continued]
// TEST[setup:my_index_huge]
// TEST[s/^/POST _reindex?refresh\n{ "source": { "index": "my-index-000001" }, "dest": { "index": "my-data-stream", "op_type": "create" } }\n/]

The API returns:

[source,console-result]
----
{
  "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,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}
----
// TESTRESPONSE[s/.ds-my-data-stream-2099.05.06-000001/$body.old_index/]
// TESTRESPONSE[s/.ds-my-data-stream-2099.05.07-000002/$body.new_index/]

////
[source,console]
----
DELETE _data_stream/*
DELETE _index_template/*
----
// TEST[continued]
////

[[roll-over-index-alias-with-write-index]]
===== Roll over an index alias with a write index

The following request creates `<my-index-{now/d}-000001>` and sets it as the
write index for `my-alias`.

[source,console]
----
# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {
      "is_write_index": true
    }
  }
}
----
// TEST[s/%3Cmy-index-%7Bnow%2Fd%7D-000001%3E/my-index-2099.05.06-000001/]

:target: alias

include::rollover-index.asciidoc[tag=rollover-conditions-ex]

[source,console]
----
POST my-alias/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}
----
// TEST[continued]
// TEST[setup:my_index_huge]
// TEST[s/^/POST _reindex?refresh\n{ "source": { "index": "my-index-000001" }, "dest": { "index": "my-alias" } }\n/]

The API returns:

[source,console-result]
----
{
  "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,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}
----
// TESTRESPONSE[s/my-index-2099.05.07-000002/my-index-2099.05.06-000002/]

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.

[source,console]
----
# 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
----

[[roll-over-index-alias-with-one-index]]
===== Roll over an index alias with one index

The following request creates `<my-index-{now/d}-000001>` and its alias, `my-write-alias`.

[source,console]
----
# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-write-alias": { }
  }
}
----
// TEST[s/%3Cmy-index-%7Bnow%2Fd%7D-000001%3E/my-index-2099.05.06-000001/]

:index: index

include::rollover-index.asciidoc[tag=rollover-conditions-ex]

:target!:
:index!:

[source,console]
----
POST my-write-alias/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}
----
// TEST[continued]
// TEST[setup:my_index_huge]
// TEST[s/^/POST _reindex?refresh\n{ "source": { "index": "my-index-000001" }, "dest": { "index": "my-write-alias" } }\n/]

The API returns:

[source,console-result]
----
{
  "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,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}
----
// TESTRESPONSE[s/my-index-2099.05.07-000002/my-index-2099.05.06-000002/]

[[specify-settings-during-rollover]]
===== Specify settings during a rollover

Typically, you use an <<index-templates,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.

[source,console]
----
POST my-alias/_rollover
{
  "settings": {
    "index.number_of_shards": 2
  }
}
----
// TEST[continued]
// TEST[s/my-alias/my-write-alias/]
