Roll over to a new index
Generally available
All methods and paths for this operation:
TIP: We recommend using the index lifecycle rollover action to automate rollovers. However, Serverless does not support Index Lifecycle Management (ILM), so don't use this approach in the Serverless context.
The rollover API creates a new index for a data stream or index alias. The API 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.
Roll over an index alias with a write index
TIP: Prior to Elasticsearch 7.9, you'd typically use an index alias with a write index to manage time series data. Data streams replace this functionality, require less maintenance, and automatically integrate with data tiers.
If an index alias points to multiple indices, one of the indices must be a 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.
NOTE: A rollover creates a new index and is subject to the wait_for_active_shards setting.
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 six characters and zero-padded, regardless of the previous index's name.
If you use an index alias for time series data, you can use 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.
Required authorization
- Index privileges:
manage
Path parameters
-
Name of the data stream or index alias to roll over.
-
Name of the index to create. Supports date math. Data streams do not support this parameter.
Query parameters
-
If
true, checks whether the current index satisfies the specified conditions but does not perform a rollover. -
Period 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.
Values are
-1or0. -
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are
-1or0. -
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).Values are
allorindex-setting. -
If set to true, the rollover action will only mark a data stream to signal that it needs to be rolled over at the next write. Only allowed on data streams.
Body
-
Aliases for the target index. Data streams do not support this parameter.
-
Conditions for the rollover. If specified, Elasticsearch only performs the rollover if the current index satisfies these conditions. If this parameter is not specified, Elasticsearch performs the rollover unconditionally. If conditions are specified, at least one of them must be a
max_*condition. The index will rollover if anymax_*condition is satisfied and allmin_*conditions are satisfied. -
Mapping for fields in the index. If specified, this mapping can include field names, field data types, and mapping paramaters.
-
Configuration options for the index. Data streams do not support this parameter.
POST my-data-stream/_rollover
{
"conditions": {
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
}
}resp = client.indices.rollover(
alias="my-data-stream",
conditions={
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
},
)const response = await client.indices.rollover({
alias: "my-data-stream",
conditions: {
max_age: "7d",
max_docs: 1000,
max_primary_shard_size: "50gb",
max_primary_shard_docs: "2000",
},
});response = client.indices.rollover(
alias: "my-data-stream",
body: {
"conditions": {
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
}
}
)$resp = $client->indices()->rollover([
"alias" => "my-data-stream",
"body" => [
"conditions" => [
"max_age" => "7d",
"max_docs" => 1000,
"max_primary_shard_size" => "50gb",
"max_primary_shard_docs" => "2000",
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"conditions":{"max_age":"7d","max_docs":1000,"max_primary_shard_size":"50gb","max_primary_shard_docs":"2000"}}' "$ELASTICSEARCH_URL/my-data-stream/_rollover"{
"conditions": {
"max_age": "7d",
"max_docs": 1000,
"max_primary_shard_size": "50gb",
"max_primary_shard_docs": "2000"
}
}{}{
"_shards": {},
"indices": {
"test": {
"shards": {
"0": [
{
"routing": {
"state": "STARTED",
"primary": true,
"node": "zDC_RorJQCao9xf9pg3Fvw"
},
"num_committed_segments": 0,
"num_search_segments": 1,
"segments": {
"_0": {
"generation": 0,
"num_docs": 1,
"deleted_docs": 0,
"size_in_bytes": 3800,
"committed": false,
"search": true,
"version": "7.0.0",
"compound": true,
"attributes": {}
}
}
}
]
}
}
}
}