IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Delete data stream API Migrate to data stream API »
Elastic Docs ›Elasticsearch Guide [7.16] ›REST APIs ›Data stream APIs

Get data stream API

edit

Get data stream API

edit

Retrieves information about one or more data streams. See Get information about a data stream.

GET /_data_stream/my-data-stream

Request

edit

GET /_data_stream/<data-stream>

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the data stream.

Path parameters

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

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.

Response body

edit
data_streams

(array of objects) Contains information about retrieved data streams.

Properties of objects in data_streams
name
(string) Name of the data stream.
timestamp_field

(object) Contains information about the data stream’s @timestamp field.

Properties of timestamp_field
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 write index.

Properties of indices objects
index_name
(string) Name of the backing index. For naming conventions, see Generation.
index_uuid
(string) Universally unique identifier (UUID) for the index.
generation
(integer) Current 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 index template. If empty, the response omits this property.
status

(string) 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
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 an index template.

ilm_policy

(string) Name of the current ILM 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.

A data stream’s backing indices may be assigned different lifecycle policies. To retrieve the lifecycle policy for individual backing indices, use the get index settings API.

hidden
(Boolean) If true, the data stream is 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.
replicated
(Boolean) If true, the data stream is created and managed by cross-cluster replication and the local cluster can not write into this data stream or change its mappings.

Examples

edit
GET _data_stream/my-data-stream*

The API returns the following response:

{
  "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"
        },
        {
          "index_name": ".ds-my-data-stream-2099.03.08-000002",
          "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw"
        }
      ],
      "generation": 2,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "GREEN",
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "replicated": 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"
        }
      ],
      "generation": 1,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "YELLOW",
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "replicated": false
    }
  ]
}
« Delete data stream API Migrate to data stream API »