[7.x] Update rollover index API docs for data streams
This commit is contained in:
Dan Hermann
GitHub
parent
259be236cf
commit
60db6c7c45
|
|
@ -4,8 +4,12 @@
|
|||
<titleabbrev>Rollover index</titleabbrev>
|
||||
++++
|
||||
|
||||
Assigns an <<indices-aliases, index alias>> to a new index
|
||||
when the alias's existing index meets a condition you provide.
|
||||
Creates a new index for a rollover target when the target's existing index meets
|
||||
a condition you provide. A rollover target can be either an
|
||||
<<indices-aliases, index alias>> or a
|
||||
<<indices-create-data-stream, data stream>>. When targeting an alias, the alias
|
||||
is updated to point to the new index. When targeting a data stream, the new
|
||||
index becomes the data stream's write index and its generation is incremented.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
|
|
@ -25,15 +29,15 @@ POST /alias1/_rollover/twitter
|
|||
==== {api-request-title}
|
||||
|
||||
|
||||
`POST /<alias>/_rollover/<target-index>`
|
||||
`POST /<rollover-target>/_rollover/<target-index>`
|
||||
|
||||
`POST /<alias>/_rollover/`
|
||||
`POST /<rollover-target>/_rollover/`
|
||||
|
||||
|
||||
[[rollover-index-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The rollover index API rolls an <<indices-aliases, alias>> to a new index when
|
||||
The rollover index API rolls a rollover target to a new index when
|
||||
the existing index meets a condition you provide. You can use this API to retire
|
||||
an index that becomes too large or too old.
|
||||
|
||||
|
|
@ -42,25 +46,29 @@ NOTE: To roll over an index, a condition must be met *when you call the API*.
|
|||
automatically roll over indices when a condition is met, you can use {es}'s
|
||||
<<index-lifecycle-management, index lifecycle management (ILM) policies>>.
|
||||
|
||||
The rollover index API accepts a single alias name
|
||||
The rollover index API accepts a rollover target name
|
||||
and a list of `conditions`.
|
||||
|
||||
If the specified alias points to a single index,
|
||||
If the specified rollover target is an alias pointing to a single index,
|
||||
the rollover request:
|
||||
|
||||
. Creates a new index
|
||||
. Adds the alias to the new index
|
||||
. Removes the alias from the original index
|
||||
|
||||
If the specified alias points to multiple indices,
|
||||
If the specified rollover target is an alias pointing to multiple indices,
|
||||
one of these indices must have `is_write_index` set to `true`.
|
||||
In this case,
|
||||
the rollover request:
|
||||
In this case, the rollover request:
|
||||
|
||||
. Creates a new index
|
||||
. Sets `is_write_index` to `true` for the new index
|
||||
. Sets `is_write_index` to `false` for the original index
|
||||
|
||||
If the specified rollover target is a data stream, the rollover request:
|
||||
|
||||
. Creates a new index
|
||||
. Adds the new index as a backing index and the write index on the data stream
|
||||
. Increments the `generation` attribute of the data stream
|
||||
|
||||
[[rollover-wait-active-shards]]
|
||||
===== Wait for active shards
|
||||
|
|
@ -73,10 +81,10 @@ index creation applies to the rollover action.
|
|||
[[rollover-index-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`<alias>`::
|
||||
(Required, string)
|
||||
Name of the existing index alias
|
||||
to assign to the target index.
|
||||
`<rollover-target>`::
|
||||
(Required*, string)
|
||||
Name of the existing index alias or data stream on which to
|
||||
to assign to the target index. perform the rollover.
|
||||
|
||||
|
||||
`<target-index>`::
|
||||
|
|
@ -87,19 +95,19 @@ Name of the target index to create and assign the index alias.
|
|||
|
||||
include::{es-repo-dir}/indices/create-index.asciidoc[tag=index-name-reqs]
|
||||
|
||||
*This parameter is not required
|
||||
if the alias is assigned to an index name that ends with `-` and a number,
|
||||
such as `logs-000001`.
|
||||
In this case,
|
||||
the name of the new index follows the same pattern,
|
||||
incrementing the number.
|
||||
For example,
|
||||
`logs-000001` increments to `logs-000002`.
|
||||
This number is zero-padded with a length of 6,
|
||||
regardless of the prior index name.
|
||||
*This parameter is not permitted if `rollover-target` is a data stream. In
|
||||
that case, the new index name will be in the form `.ds-<rollover-target>-000001`
|
||||
where the zero-padded number of length 6 is the generation of the data stream.
|
||||
|
||||
If `rollover-target` is an alias that is assigned to an index name that ends
|
||||
with `-` and a number such as `logs-000001`. In this case, the name of the new
|
||||
index follows the same pattern and increments the number. For example,
|
||||
`logs-000001` increments to `logs-000002`. This number is zero-padded with a
|
||||
length of 6, regardless of the prior index name.
|
||||
|
||||
If the existing index for the alias does not match this pattern, this parameter
|
||||
is required.
|
||||
|
||||
If the existing index for the alias does not match this pattern,
|
||||
this parameter is required.
|
||||
--
|
||||
|
||||
|
||||
|
|
@ -128,8 +136,9 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=aliases]
|
|||
`conditions`::
|
||||
+
|
||||
--
|
||||
(Required, object)
|
||||
Set of conditions the index alias's existing index must met to roll over.
|
||||
(Optional, object)
|
||||
If supplied, the set of conditions the rollover target's existing index must
|
||||
meet to roll over. If omitted, the rollover will be performed unconditionally.
|
||||
|
||||
Parameters include:
|
||||
|
||||
|
|
@ -298,11 +307,12 @@ DELETE /_index_template/*
|
|||
===== Specify settings for the target index
|
||||
|
||||
The settings, mappings, and aliases for the new index are taken from any
|
||||
matching <<indices-templates,index templates>>. Additionally, you can specify
|
||||
`settings`, `mappings`, and `aliases` in the body of the request, just like the
|
||||
<<indices-create-index,create index>> API. Values specified in the request
|
||||
override any values set in matching index templates. For example, the following
|
||||
`rollover` request overrides the `index.number_of_shards` setting:
|
||||
matching <<indices-templates,index templates>>. If the rollover target is an
|
||||
index alias, you can specify `settings`, `mappings`, and `aliases` in the body
|
||||
of the request just like the <<indices-create-index,create index>> API. Values
|
||||
specified in the request override any values set in matching index templates.
|
||||
For example, the following `rollover` request overrides the
|
||||
`index.number_of_shards` setting:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
|
|
@ -330,10 +340,10 @@ POST /logs_write/_rollover
|
|||
[[rollover-index-specify-index-ex]]
|
||||
===== Specify a target index name
|
||||
|
||||
If the name of the existing index ends with `-` and a number -- e.g.
|
||||
`logs-000001` -- then the name of the new index will follow the same pattern,
|
||||
incrementing the number (`logs-000002`). The number is zero-padded with a length
|
||||
of 6, regardless of the old index name.
|
||||
If the rollover target is an index alias and the name of the existing index ends
|
||||
with `-` and a number -- e.g. `logs-000001` -- then the name of the new index
|
||||
will follow the same pattern, incrementing the number (`logs-000002`). The
|
||||
number is zero-padded with a length of 6, regardless of the old index name.
|
||||
|
||||
If the old name doesn't match this pattern then you must specify the name for
|
||||
the new index as follows:
|
||||
|
|
@ -355,12 +365,12 @@ POST /my_alias/_rollover/my_new_index_name
|
|||
[[_using_date_math_with_the_rollover_api]]
|
||||
===== Use date math with a rollover
|
||||
|
||||
It can be useful to use <<date-math-index-names,date math>> to name the
|
||||
rollover index according to the date that the index rolled over, e.g.
|
||||
`logstash-2016.02.03`. The rollover API supports date math, but requires the
|
||||
index name to end with a dash followed by a number, e.g.
|
||||
`logstash-2016.02.03-1` which is incremented every time the index is rolled
|
||||
over. For instance:
|
||||
If the rollover target is an index alias, it can be useful to use
|
||||
<<date-math-index-names,date math>> to name the rollover index according to the
|
||||
date that the index rolled over, e.g. `logstash-2016.02.03`. The rollover API
|
||||
supports date math, but requires the index name to end with a dash followed by
|
||||
a number, e.g. `logstash-2016.02.03-1` which is incremented every time the
|
||||
index is rolled over. For instance:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
|
|
@ -453,7 +463,7 @@ POST /logs_write/_rollover?dry_run
|
|||
[[indices-rollover-is-write-index]]
|
||||
===== Roll over a write index
|
||||
|
||||
The rollover alias when rolling over a write index that has `is_write_index` explicitly set to `true` is not
|
||||
If the rollover target is an index alias for a write index that has `is_write_index` explicitly set to `true`, it is not
|
||||
swapped during rollover actions. Since having an alias point to multiple indices is ambiguous in distinguishing
|
||||
which is the correct write index to roll over, it is not valid to rollover an alias that points to multiple indices.
|
||||
For this reason, the default behavior is to swap which index is being pointed to by the write-oriented alias. This
|
||||
|
|
|
|||
Loading…
Reference in New Issue