mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 18:03:32 -04:00
a7e65e3b2d
The documentation specifies the possible values for the status of the response. This endpoint is inconsistent with most others that expose the health status as it returns the values as uppercase strings rather than lowercase. This PR fixes the cases in the documentation to align with the actual values returned in the response body.
294 lines
7.2 KiB
Text
294 lines
7.2 KiB
Text
[role="xpack"]
|
|
[[indices-get-data-stream]]
|
|
=== Get data stream API
|
|
++++
|
|
<titleabbrev>Get data stream</titleabbrev>
|
|
++++
|
|
|
|
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
|
|
----
|
|
// 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-repo-dir}/rest-api/common-parms.asciidoc[tag=ds-expand-wildcards]
|
|
+
|
|
Defaults to `open`.
|
|
|
|
[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.
|
|
=====
|
|
|
|
`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>>.
|
|
|
|
`hidden`::
|
|
(Boolean) If `true`, the data stream is <<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.
|
|
====
|
|
|
|
[[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"
|
|
},
|
|
{
|
|
"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,
|
|
"allow_custom_routing": 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,
|
|
"allow_custom_routing": false,
|
|
"replicated": 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"/]
|