Rollover index API
editRollover index API
editAssigns an index alias to a new index when the alias’s existing index meets a condition you provide.
POST /alias1/_rollover/twitter { "conditions": { "max_age": "7d", "max_docs": 1000, "max_size": "5gb" } }
Description
editThe rollover index API rolls an alias 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.
To roll over an index, a condition must be met when you call the API. Elasticsearch does not monitor the index after you receive an API response. To automatically roll over indices when a condition is met, you can use Elasticsearch’s index lifecycle management (ILM) policies.
The rollover index API accepts a single alias name
and a list of conditions
.
If the specified alias points 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,
one of these indices must have is_write_index
set to true
.
In this case,
the rollover request:
- Creates a new index
-
Sets
is_write_index
totrue
for the new index -
Sets
is_write_index
tofalse
for the original index
Wait for active shards
editBecause the rollover operation creates a new index to rollover to, the
wait_for_active_shards
setting on
index creation applies to the rollover action.
Path parameters
edit-
<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.
Index names must meet the following criteria:
- Lowercase only
-
Cannot include
\
,/
,*
,?
,"
,<
,>
,|
, ` ` (space character),,
,#
-
Indices prior to 7.0 could contain a colon (
:
), but that’s been deprecated and won’t be supported in 7.0+ -
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)
-
Names starting with
.
are deprecated, except for hidden indices and internal indices managed by plugins
*This parameter is not required if the alias is assigned to an index name that ends with
-
and a number, such aslogs-000001
. In this case, the name of the new index follows the same pattern, incrementing the number. For example,logs-000001
increments tologs-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.
Query parameters
edit-
dry_run
-
(Optional, boolean)
If
true
, the request checks whether the index matches provided conditions but does not perform a rollover. Defaults tofalse
. -
include_type_name
-
[7.0.0]
Deprecated in 7.0.0. Mapping types have been deprecated. See Removal of mapping types.
(Optional, boolean) If
true
, a mapping type is expected in the body of mappings. Defaults tofalse
. -
wait_for_active_shards
-
(Optional, string) The number of shard copies that must be active before proceeding with the operation. Set to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). Default: 1, the primary shard.See Active shards.
-
master_timeout
-
(Optional, time units) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to
30s
. -
timeout
-
(Optional, time units) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to
30s
.
Request body
edit-
aliases
- (Optional, alias object) Index aliases which include the index. See Update index alias.
-
conditions
-
(Required, object) Set of conditions the index alias’s existing index must met to roll over.
Parameters include:
-
max_age
- (Optional, time units) Maximum age of the index.
-
max_docs
- (Optional, integer) Maximum number of documents in the index. Documents added since the last refresh are not included in the document count. The document count does not include documents in replica shards.
-
max_size
- (Optional, byte units) Maximum index size. This is the total size of all primary shards in the index. Replicas are not counted toward the maximum index size.
To see the current index size, use the _cat indices API. The
pri.store.size
value shows the combined size of all primary shards. -
-
mappings
-
(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:
- Field names
- Field datatypes
- Mapping parameters
See Mapping.
-
settings
- (Optional, index setting object) Configuration options for the index. See Index Settings.
Examples
editBasic example
editPUT /logs-000001 { "aliases": { "logs_write": {} } } # Add > 1000 documents to logs-000001 POST /logs_write/_rollover { "conditions": { "max_age": "7d", "max_docs": 1000, "max_size": "5gb" } }
Creates an index called |
|
If the index pointed to by |
The API returns the following response:
Specify settings for the target index
editThe settings, mappings, and aliases for the new index are taken from any
matching index templates. Additionally, you can specify
settings
, mappings
, and aliases
in the body of the request, just like the
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:
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 } }
Specify a target index name
editIf 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:
POST /my_alias/_rollover/my_new_index_name { "conditions": { "max_age": "7d", "max_docs": 1000, "max_size": "5gb" } }
Use date math with a rollover
editIt can be useful to use 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:
# PUT /<logs-{now/d}-1> with URI encoding: PUT /%3Clogs-%7Bnow%2Fd%7D-1%3E { "aliases": { "logs_write": {} } } PUT logs_write/_doc/1 { "message": "a dummy log" } POST logs_write/_refresh # Wait for a day to pass POST /logs_write/_rollover { "conditions": { "max_docs": "1" } }
Creates an index named with today’s date (e.g.) |
|
Rolls over to a new index with today’s date, e.g. |
These indices can then be referenced as described in the date math documentation. For example, to search over indices created in the last three days, you could do the following:
# GET /<logs-{now/d}-*>,<logs-{now/d-1d}-*>,<logs-{now/d-2d}-*>/_search GET /%3Clogs-%7Bnow%2Fd%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-1d%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-2d%7D-*%3E/_search
Dry run
editThe rollover API supports dry_run
mode, where request conditions can be
checked without performing the actual rollover.
POST /logs_write/_rollover?dry_run { "conditions" : { "max_age": "7d", "max_docs": 1000, "max_size": "5gb" } }
Roll over a write index
editThe 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
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
was logs_write
in some of the above examples. Since setting is_write_index
enables an alias to point to multiple indices
while also being explicit as to which is the write index that rollover should target, removing the alias from the rolled over
index is not necessary. This simplifies things by allowing for one alias to behave both as the write and read aliases for
indices that are being managed with Rollover.
Look at the behavior of the aliases in the following example where is_write_index
is set on the rolled over index.
PUT my_logs_index-000001 { "aliases": { "logs": { "is_write_index": true } } } PUT logs/_doc/1 { "message": "a dummy log" } POST logs/_refresh POST /logs/_rollover { "conditions": { "max_docs": "1" } } PUT logs/_doc/2 { "message": "a newer log" }
configures |
|
newly indexed documents against the |
{ "_index" : "my_logs_index-000002", "_type" : "_doc", "_id" : "2", "_version" : 1, "result" : "created", "_shards" : { "total" : 2, "successful" : 1, "failed" : 0 }, "_seq_no" : 0, "_primary_term" : 1 }
After the rollover, the alias metadata for the two indices will have the is_write_index
setting
reflect each index’s role, with the newly created index as the write index.
{ "my_logs_index-000002": { "aliases": { "logs": { "is_write_index": true } } }, "my_logs_index-000001": { "aliases": { "logs": { "is_write_index" : false } } } }