mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 09:28:55 -04:00
920290a37b
We were seeing more and more common fields between "regular" backing indices and failure store indices (i.e. `indices`, `rolloverOnWrite`, `autoShardingEvent`). To avoid having to duplicate these fields (and possibly any future fields), we extract a class that contains these fields.
361 lines
10 KiB
Text
361 lines
10 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
|
|
|
|
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`.
|
|
|
|
[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_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"
|
|
}
|
|
],
|
|
"generation": 2,
|
|
"_meta": {
|
|
"my-meta-field": "foo"
|
|
},
|
|
"status": "GREEN",
|
|
"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"
|
|
}
|
|
],
|
|
"generation": 1,
|
|
"_meta": {
|
|
"my-meta-field": "foo"
|
|
},
|
|
"status": "YELLOW",
|
|
"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": false}/]
|