[DOCS] Reformat rollover index API docs (#46778)
This commit is contained in:
James Rodewig
parent
2da040601b
commit
b09aba4c55
|
|
@ -35,6 +35,7 @@ creating an index, you can specify the following:
|
|||
--
|
||||
(Optional, string) Name of the index you wish to create.
|
||||
|
||||
// tag::index-name-reqs[]
|
||||
Index names must meet the following criteria:
|
||||
|
||||
- Lowercase only
|
||||
|
|
@ -43,6 +44,7 @@ Index names must meet the following criteria:
|
|||
- Cannot start with `-`, `_`, `+`
|
||||
- Cannot be `.` or `..`
|
||||
- Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster)
|
||||
// end::index-name-reqs[]
|
||||
--
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,37 @@
|
|||
[[indices-rollover-index]]
|
||||
=== Rollover Index
|
||||
=== Rollover index API
|
||||
++++
|
||||
<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.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
POST /alias1/_rollover/twitter
|
||||
{
|
||||
"conditions": {
|
||||
"max_age": "7d",
|
||||
"max_docs": 1000,
|
||||
"max_size": "5gb"
|
||||
}
|
||||
}
|
||||
----
|
||||
// TEST[s/^/PUT my_old_index_name\nPUT my_old_index_name\/_alias\/alias1\n/]
|
||||
|
||||
|
||||
[[rollover-index-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
|
||||
`POST /<alias>/_rollover/<target-index>`
|
||||
|
||||
`POST /<alias>/_rollover/`
|
||||
|
||||
|
||||
[[rollover-index-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The rollover index API rolls an <<indices-aliases, alias>> to a new index when
|
||||
the existing index meets a condition you provide. You can use this API to retire
|
||||
|
|
@ -24,17 +56,102 @@ from the original (rolled-over) index.
|
|||
In this scenario, the write index will have its rollover alias' `is_write_index` set to `false`, while the newly created index
|
||||
will now have the rollover alias pointing to it as the write index with `is_write_index` as `true`.
|
||||
|
||||
The available conditions are:
|
||||
|
||||
[[index-rollover-conditions]]
|
||||
.`conditions` parameters
|
||||
[options="header"]
|
||||
|===
|
||||
| Name | Description
|
||||
| max_age | The maximum age of the index
|
||||
| max_docs | The maximum number of documents the index should contain. This does not add documents multiple times for replicas
|
||||
| max_size | The maximum estimated size of the primary shard of the index
|
||||
|===
|
||||
[[rollover-wait-active-shards]]
|
||||
===== Wait for active shards
|
||||
|
||||
Because the rollover operation creates a new index to rollover to, the
|
||||
<<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
|
||||
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.
|
||||
|
||||
|
||||
`<target-index>`::
|
||||
+
|
||||
--
|
||||
(Optional*, string)
|
||||
Name of the target index to create and assign the index alias.
|
||||
|
||||
include::{docdir}/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.
|
||||
|
||||
If the existing index for the alias does not match this pattern,
|
||||
this parameter is required.
|
||||
--
|
||||
|
||||
|
||||
[[rollover-index-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
`dry_run`::
|
||||
(Optional, boolean)
|
||||
If `true`,
|
||||
the request checks whether the index matches provided conditions
|
||||
but does not perform a rollover.
|
||||
Defaults to `false`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
|
||||
[[rollover-index-api-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases]
|
||||
|
||||
`conditions`::
|
||||
+
|
||||
--
|
||||
(Required, object)
|
||||
Set of conditions the index alias's existing index must met to roll over.
|
||||
|
||||
Parameters include:
|
||||
|
||||
`max_age`::
|
||||
(Optional, <<time-units, time units>>)
|
||||
Maximum age of the index.
|
||||
|
||||
`max_docs`::
|
||||
(Optional, integer)
|
||||
Maximum number of documents in the index.
|
||||
This number does *not* include documents in replica shards.
|
||||
|
||||
`max_size`::
|
||||
(Optional, <<byte-units, byte units>>)
|
||||
Maximum estimated size of the primary shard of the index.
|
||||
--
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=settings]
|
||||
|
||||
|
||||
[[rollover-index-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
[[rollover-index-basic-ex]]
|
||||
===== Basic example
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
|
|
@ -63,7 +180,7 @@ POST /logs_write/_rollover <2>
|
|||
contains 1,000 or more documents, or has an index size at least around 5GB, then the `logs-000002` index is created
|
||||
and the `logs_write` alias is updated to point to `logs-000002`.
|
||||
|
||||
The above request might return the following response:
|
||||
The API returns the following response:
|
||||
|
||||
[source,console-result]
|
||||
--------------------------------------------------
|
||||
|
|
@ -86,8 +203,41 @@ The above request might return the following response:
|
|||
<2> Whether the rollover was dry run.
|
||||
<3> The result of each condition.
|
||||
|
||||
[float]
|
||||
==== Naming the new index
|
||||
[[rollover-index-settings-ex]]
|
||||
===== 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:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /logs-000001
|
||||
{
|
||||
"aliases": {
|
||||
"logs_write": {}
|
||||
}
|
||||
}
|
||||
|
||||
POST /logs_write/_rollover
|
||||
{
|
||||
"conditions" : {
|
||||
"max_age": "7d",
|
||||
"max_docs": 1000,
|
||||
"max_size": "5gb"
|
||||
},
|
||||
"settings": {
|
||||
"index.number_of_shards": 2
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
[[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,
|
||||
|
|
@ -110,8 +260,9 @@ POST /my_alias/_rollover/my_new_index_name
|
|||
--------------------------------------------------
|
||||
// TEST[s/^/PUT my_old_index_name\nPUT my_old_index_name\/_alias\/my_alias\n/]
|
||||
|
||||
[float]
|
||||
==== Using date math with the rollover API
|
||||
|
||||
[[_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.
|
||||
|
|
@ -187,53 +338,15 @@ GET /%3Clogs-%7Bnow%2Fd%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-1d%7D-*%3E%2C%3Clogs-%7Bnow
|
|||
// TEST[continued]
|
||||
// TEST[s/now/2016.10.31||/]
|
||||
|
||||
[float]
|
||||
==== Defining the new 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:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /logs-000001
|
||||
{
|
||||
"aliases": {
|
||||
"logs_write": {}
|
||||
}
|
||||
}
|
||||
|
||||
POST /logs_write/_rollover
|
||||
{
|
||||
"conditions" : {
|
||||
"max_age": "7d",
|
||||
"max_docs": 1000,
|
||||
"max_size": "5gb"
|
||||
},
|
||||
"settings": {
|
||||
"index.number_of_shards": 2
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[float]
|
||||
==== Dry run
|
||||
[[rollover-index-api-dry-run-ex]]
|
||||
===== Dry run
|
||||
|
||||
The rollover API supports `dry_run` mode, where request conditions can be
|
||||
checked without performing the actual rollover:
|
||||
checked without performing the actual rollover.
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /logs-000001
|
||||
{
|
||||
"aliases": {
|
||||
"logs_write": {}
|
||||
}
|
||||
}
|
||||
|
||||
POST /logs_write/_rollover?dry_run
|
||||
{
|
||||
"conditions" : {
|
||||
|
|
@ -243,17 +356,11 @@ POST /logs_write/_rollover?dry_run
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TEST[s/^/PUT logs-000001\nPUT logs-000001\/_alias\/logs_write\n/]
|
||||
|
||||
[float]
|
||||
==== Wait For Active Shards
|
||||
|
||||
Because the rollover operation creates a new index to rollover to, the
|
||||
<<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
|
||||
index creation applies to the rollover action as well.
|
||||
|
||||
[[indices-rollover-is-write-index]]
|
||||
[float]
|
||||
==== Write Index Alias Behavior
|
||||
===== 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
|
||||
swapped during rollover actions. Since having an alias point to multiple indices is ambiguous in distinguishing
|
||||
|
|
|
|||
Loading…
Reference in New Issue