mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
33a71e3289
* Remove `es-test-dir` book-scoped variable * Remove `plugins-examples-dir` book-scoped variable * Remove `:dependencies-dir:` and `:xes-repo-dir:` book-scoped variables - In `index.asciidoc`, two variables (`:dependencies-dir:` and `:xes-repo-dir:`) were removed. - In `sql/index.asciidoc`, the `:sql-tests:` path was updated to fuller path - In `esql/index.asciidoc`, the `:esql-tests:` path was updated idem * Replace `es-repo-dir` with `es-ref-dir` * Move `:include-xpack: true` to few files that use it, remove from index.asciidoc
454 lines
13 KiB
Text
454 lines
13 KiB
Text
[[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/]
|