elasticsearch/docs/reference/data-streams/lifecycle/apis/put-lifecycle.asciidoc

[[data-streams-put-lifecycle]]
=== Set the lifecycle of a data stream
++++
<titleabbrev>Put Data Stream Lifecycle</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-data-stream[Data stream APIs].
--

Configures the data stream <<data-stream-lifecycle,lifecycle>> for the targeted <<data-streams,data streams>>.

[[put-lifecycle-api-prereqs]]
==== {api-prereq-title}

If the {es} {security-features} are enabled, you must have the `manage_data_stream_lifecycle` index privilege or higher to use this API.
For more information, see <<security-privileges>>.

[[data-streams-put-lifecycle-request]]
==== {api-request-title}

`PUT _data_stream/<data-stream>/_lifecycle`

[[data-streams-put-lifecycle-desc]]
==== {api-description-title}

Configures the data stream lifecycle for the targeted data streams. If multiple data streams are provided but at least one of them
does not exist, then the update of the lifecycle will fail for all of them and the API will respond with `404`.

[[data-streams-put-lifecycle-path-params]]
==== {api-path-parms-title}

`<data-stream>`::
(Required, string) Comma-separated list of data streams used to limit the request. Supports wildcards (`*`).
To target all data streams use `*` or `_all`.

[role="child_attributes"]
[[put-data-lifecycle-api-query-parms]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=ds-expand-wildcards]
+
Defaults to `open`.

[[put-lifecycle-api-request-body]]
==== {api-request-body-title}

`lifecycle`::
(Required, object)
+
.Properties of `lifecycle`
[%collapsible%open]
====
`data_retention`::
(Optional, string)
If defined, every document added to this data stream will be stored at least for this time frame. Any time after this
duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely.

`enabled`::
(Optional, boolean)
If defined, it turns data stream lifecycle on/off (`true`/`false`) for this data stream.
A data stream lifecycle that's disabled (`enabled: false`) will have no effect on the
data stream. Defaults to `true`.

`downsampling`::
(Optional, array)
An optional array of downsampling configuration objects, each defining an `after`
interval representing when the backing index is meant to be downsampled (the time 
frame is calculated since the index was rolled over, i.e. generation time) and
a `fixed_interval` representing the downsampling interval (the minimum `fixed_interval`
value is `5m`). A maximum number of 10 downsampling rounds can be configured.
See <<data-streams-put-lifecycle-downsampling-example, configuration example>> below.

====

[[data-streams-put-lifecycle-example]]
==== {api-examples-title}

The following example sets the lifecycle of `my-data-stream`:

[source,console]
--------------------------------------------------
PUT _data_stream/my-data-stream/_lifecycle
{
  "data_retention": "7d"
}
--------------------------------------------------
// TEST[setup:my_data_stream]
// TEST[teardown:data_stream_cleanup]

When the lifecycle is successfully updated in all data streams, you receive the following result:

[source,console-result]
--------------------------------------------------
{
  "acknowledged": true
}
--------------------------------------------------

[[data-streams-put-lifecycle-downsampling-example]]
==== {api-examples-title}

The following example configures two downsampling rounds, the first one starting
one day after the backing index is rolled over (or later, if the index is still 
within its write-accepting <<time-bound-indices, time bounds>>) with an interval
of `10m`, and a second round starting 7 days after rollover at an interval of `1d`:

[source,console]
--------------------------------------------------------------------
PUT _data_stream/my-weather-sensor-data-stream/_lifecycle
{
    "downsampling": [
      {
        "after": "1d",
        "fixed_interval": "10m"
      },
      {
        "after": "7d",
        "fixed_interval": "1d"
      }
    ]
}
--------------------------------------------------------------------
//TEST[skip:downsampling requires waiting for indices to be out of time bounds]