This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

« Set the lifecycle of a data stream Delete the lifecycle of a data stream »

› › ›

Get the lifecycle of a data stream

edit

Get the lifecycle of a data stream

edit

Gets the lifecycle of a set of data streams.

Prerequisites

edit

If the Elasticsearch security features are enabled, you must have at least one of the manage index privilege, the manage_data_stream_lifecycle index privilege, or the view_index_metadata privilege to use this API. For more information, see Security privileges.

Request

edit

GET _data_stream/<data-stream>/_lifecycle

Description

edit

Gets the lifecycle of the specified data streams. If multiple data streams are requested but at least one of them does not exist, then the API will respond with 404 since at least one of the requested resources could not be retrieved. If the requested data streams do not have a lifecycle configured they will still be included in the API response but the lifecycle key will be missing.

Path parameters

edit

<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.

Query parameters

edit

expand_wildcards

(Optional, string) Type of data stream that wildcard patterns can match. Supports comma-separated values, such as open,hidden. Valid values are:

all, hidden: Match any data stream, including hidden ones.
open, closed: Matches any non-hidden data stream. Data streams cannot be closed.
none: Wildcard patterns are not accepted.

Defaults to open.

include_defaults

(Optional, Boolean) If true, return all default settings in the response. Defaults to false.

Response body

edit

data_streams

(array of objects) Contains information about retrieved data stream lifecycles.

Properties of objects in data_streams

name

(string) Name of the data stream.

lifecycle

(Optional, object)

Properties of lifecycle

data_retention: (Optional, string) If defined, it represents the retention requested by the data stream owner for this data stream.
effective_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. duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely. The effective retention is calculated as described in the tutorial.
retention_determined_by: (Optional, string) The source of the retention, it can be one of three values, data_stream_configuration, default_retention or max_retention.
rollover: (Optional, object) The conditions which will trigger the rollover of a backing index as configured by the cluster setting cluster.lifecycle.default.rollover. This property is an implementation detail and it will only be retrieved when the query param include_defaults is set to true. The contents of this field are subject to change.

global_retention

(object) Contains the global max and default retention. When no global retention is configured, this will be an empty object.

Properties of global_retention

max_retention: (Optional, string) The effective retention of data streams managed by the data stream lifecycle cannot exceed this value.
default_retention: (Optional, string) This will be the effective retention of data streams managed by the data stream lifecycle that do not specify data_retention.

Examples

edit

Let’s retrieve the lifecycles:

resp = client.indices.get_data_lifecycle(
    name="my-data-stream*",
)
print(resp)

response = client.indices.get_data_lifecycle(
  name: 'my-data-stream*'
)
puts response

const response = await client.indices.getDataLifecycle({
  name: "my-data-stream*",
});
console.log(response);

GET _data_stream/my-data-stream*/_lifecycle

The response will look like the following:

{
  "data_streams": [
    {
      "name": "my-data-stream-1",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d",
        "effective_retention": "7d",
        "retention_determined_by": "data_stream_configuration"
      }
    },
    {
      "name": "my-data-stream-2",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d",
        "effective_retention": "7d",
        "retention_determined_by": "data_stream_configuration"
      }
    }
  ],
  "global_retention": {}
}

« Set the lifecycle of a data stream Delete the lifecycle of a data stream »