elasticsearch/docs/reference/indices/get-data-stream.asciidoc

[role="xpack"]
[[indices-get-data-stream]]
=== Get data stream API
++++
<titleabbrev>Get data stream</titleabbrev>
++++

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

Retrieves information about one or more <<data-streams,data streams>>.
See <<get-info-about-data-stream>>.

////
[source,console]
----
PUT /_ilm/policy/my-lifecycle-policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_primary_shard_size": "25GB"
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

PUT /_index_template/my-index-template
{
  "index_patterns": [ "my-data-stream*" ],
  "data_stream": {},
  "template": {
    "settings": {
      "index.lifecycle.name": "my-lifecycle-policy"
    }
  },
  "_meta": {
    "my-meta-field": "foo"
  }
}

PUT /_data_stream/my-data-stream

POST /my-data-stream/_rollover

PUT /_data_stream/my-data-stream-two

DELETE /_data_stream/my-data-stream*/_lifecycle
----
// TESTSETUP
////

////
[source,console]
----
DELETE /_data_stream/*
DELETE /_index_template/*
DELETE /_ilm/policy/my-lifecycle-policy
----
// TEARDOWN
////

[source,console]
----
GET /_data_stream/my-data-stream
----

[[get-data-stream-api-request]]
==== {api-request-title}

`GET /_data_stream/<data-stream>`

[[get-data-stream-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
for the data stream.

[[get-data-stream-api-path-params]]
==== {api-path-parms-title}

`<data-stream>`::
(Optional, string)
Comma-separated list of data stream names used to limit the request. Wildcard
(`*`) expressions are supported. If omitted, all data streams will be
returned.

[role="child_attributes"]
[[get-data-stream-api-query-parms]]
==== {api-query-parms-title}

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

`include_defaults`::
(Optional, Boolean) Functionality in preview:[]. If `true`, return all default settings in the response.
Defaults to `false`.

`verbose`::
(Optional, Boolean). If `true`, Returns the `maximum_timestamp` corresponding to the `@timestamp` field for documents in the data stream.
Defaults to `false`.

[role="child_attributes"]
[[get-data-stream-api-response-body]]
==== {api-response-body-title}

`data_streams`::
(array of objects)
Contains information about retrieved data streams.
+
.Properties of objects in `data_streams`
[%collapsible%open]
====
`name`::
(string)
Name of the data stream.

`timestamp_field`::
(object)
Contains information about the data stream's `@timestamp` field.
+
.Properties of `timestamp_field`
[%collapsible%open]
=====
`name`::
(string)
Name of the data stream's timestamp field, which must be `@timestamp`. The
`@timestamp` field must be included in every document indexed to the data
stream.
=====

`indices`::
(array of objects)
Array of objects containing information about the data stream's backing
indices.
+
The last item in this array contains information about the stream's current
<<data-stream-write-index,write index>>.
+
.Properties of `indices` objects
[%collapsible%open]
=====
`index_name`::
(string)
Name of the backing index. For naming conventions, see
<<data-streams-generation>>.

`index_uuid`::
(string)
Universally unique identifier (UUID) for the index.

`prefer_ilm`::
(boolean)
Functionality in preview:[]. Indicates if this index is configured to prefer {ilm}
when both {ilm-cap} and <<data-stream-lifecycle, Data stream lifecycle>> are configured to
manage this index.

`managed_by`::
(string)
Functionality in preview:[]. Indicates the system that managed this index.
=====

`generation`::
(integer)
Current <<data-streams-generation,generation>> for the data stream. This number
acts as a cumulative count of the stream's rollovers, starting at `1`.

`_meta`::
(object)
Custom metadata for the stream, copied from the `_meta` object of the
stream's matching <<create-index-template,index template>>. If empty,
the response omits this property.

`status`::
(string)
<<cluster-health,Health status>> of the data stream.
+
This health status is based on the state of the primary and replica shards of
the stream's backing indices.
+
.Values for `status`
[%collapsible%open]
=====
`GREEN`:::
All shards are assigned.

`YELLOW`:::
All primary shards are assigned, but one or more replica shards are
unassigned.

`RED`:::
One or more primary shards are unassigned, so some data is unavailable.
=====

`template`::
(string)
Name of the index template used to create the data stream's backing indices.
+
The template's index pattern must match the name of this data stream. See
<<create-index-template,create an index template>>.

`ilm_policy`::
(string)
Name of the current {ilm-init} lifecycle policy in the stream's matching index
template. This lifecycle policy is set in the `index.lifecycle.name` setting.
+
If the template does not include a lifecycle policy, this property is not
included in the response.
+
NOTE: A data stream's backing indices may be assigned different lifecycle
policies. To retrieve the lifecycle policy for individual backing indices,
use the <<indices-get-settings,get index settings API>>.

`next_generation_managed_by`::
(string)
Functionality in preview:[]. Indicates the system that will managed the next generation index
(i.e. the next data stream write index).

`prefer_ilm`::
(boolean)
Functionality in preview:[]. Indicates if the index template used to create the data
stream's backing indices is configured to prefer {ilm-cap} when both {ilm-cap} and
<<data-stream-lifecycle, Data stream lifecycle>> are configured to manage this index.

`hidden`::
(Boolean) If `true`, the data stream is <<multi-hidden,hidden>>.

`system`::
(Boolean)
If `true`, the data stream is created and managed by an Elastic stack component
and cannot be modified through normal user interaction.

`allow_custom_routing`::
(Boolean)
If `true`, the data stream this data stream allows custom routing on write request.

`replicated`::
(Boolean)
If `true`, the data stream is created and managed by {ccr} and the local
cluster can not write into this data stream or change its mappings.

`lifecycle`::
(object)
Functionality in preview:[]. Contains the configuration for the data stream lifecycle management of this data stream.
+
.Properties of `lifecycle`
[%collapsible%open]
=====
`data_retention`::
(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.

`rollover`::
(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.
=====

`rollover_on_write`::
(Boolean)
If `true`, the next write to this data stream will trigger a rollover first and the document will be
indexed in the new backing index. If the rollover fails the indexing request will fail too.
====

[[get-data-stream-api-example]]
==== {api-examples-title}

[source,console]
----
GET _data_stream/my-data-stream*
----

The API returns the following response:

[source,console-result]
----
{
  "data_streams": [
    {
      "name": "my-data-stream",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-2099.03.07-000001",
          "index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management",
          "index_mode": "standard"
        },
        {
          "index_name": ".ds-my-data-stream-2099.03.08-000002",
          "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management",
          "index_mode": "standard"
        }
      ],
      "generation": 2,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "GREEN",
      "index_mode": "standard",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    },
    {
      "name": "my-data-stream-two",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-two-2099.03.08-000001",
          "index_uuid": "3liBu2SYS5axasRt6fUIpA",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management",
          "index_mode": "standard"
        }
      ],
      "generation": 1,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "YELLOW",
      "index_mode": "standard",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    }
  ]
}
----
// TESTRESPONSE[s/"index_name": ".ds-my-data-stream-2099.03.07-000001"/"index_name": $body.data_streams.0.indices.0.index_name/]
// TESTRESPONSE[s/"index_uuid": "xCEhwsp8Tey0-FLNFYVwSg"/"index_uuid": $body.data_streams.0.indices.0.index_uuid/]
// TESTRESPONSE[s/"index_name": ".ds-my-data-stream-2099.03.08-000002"/"index_name": $body.data_streams.0.indices.1.index_name/]
// TESTRESPONSE[s/"index_uuid": "PA_JquKGSiKcAKBA8DJ5gw"/"index_uuid": $body.data_streams.0.indices.1.index_uuid/]
// TESTRESPONSE[s/"index_name": ".ds-my-data-stream-two-2099.03.08-000001"/"index_name": $body.data_streams.1.indices.0.index_name/]
// TESTRESPONSE[s/"index_uuid": "3liBu2SYS5axasRt6fUIpA"/"index_uuid": $body.data_streams.1.indices.0.index_uuid/]
// TESTRESPONSE[s/"status": "GREEN"/"status": "YELLOW"/]
// TESTRESPONSE[s/"replicated": false/"replicated": false,"failure_store":{"enabled": false, "indices": [], "rollover_on_write": true}/]