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

[[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-repo-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
<<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 <<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-repo-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 matches one or more specified
`conditions` but does not perform a rollover. Defaults to `false`.

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

include::{es-repo-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-repo-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 meets one or more of these conditions. If this parameter is
not specified, {es} performs the rollover unconditionally.
+
IMPORTANT: To trigger a rollover, the current index must meet 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-repo-dir}/ilm/actions/ilm-rollover.asciidoc[tag=rollover-conditions]
====

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

include::{es-repo-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 at rollover.
====

[[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]

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