[[indices-rollover-index]] === Rollover API ++++ Rollover ++++ Creates a new index for a <> or <>. [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/` `POST //_rollover/` [[rollover-index-api-prereqs]] ==== {api-prereq-title} * If the {es} {security-features} are enabled, you must have the `manage` <> for the rollover target. [[rollover-index-api-desc]] ==== {api-description-title} TIP: We recommend using {ilm-init}'s <> action to automate rollovers. See <>. 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 <>. **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 <>. ==== If an index alias points to multiple indices, one of the indices must be a <>. 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 <> in the index name to track the rollover date. For example, you can create an alias that points to an index named ``. 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 <>. **** [[rollover-wait-active-shards]] ===== Wait for active shards A rollover creates a new index and is subject to the <> setting. [[rollover-index-api-path-params]] ==== {api-path-parms-title} ``:: (Required, string) Name of the data stream or index alias to roll over. ``:: (Optional, string) Name of the index to create. Supports <>. 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 satisfies the 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 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 <> 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 <> 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] ==== ``:: (Boolean) The key is each condition. The value is its result. If `true`, the index met the condition. ==== [[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", "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, "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 `` and sets it as the write index for `my-alias`. [source,console] ---- # PUT 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, "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 /,,/_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 `` and its alias, `my-write-alias`. [source,console] ---- # PUT 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, "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 <> 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/]