mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
Add index mode to get data stream API (#122486)
This commit adds the `index_mode` for both the data stream and each backing index to the output of `GET /_data_stream`. An example looks like: ``` { "data_streams" : [ { "name" : "foo-things", "indices" : [ { "index_name" : ".ds-foo-things-2025.02.13-000001", ... "index_mode" : "standard" } ], ... "index_mode" : "standard" }, { "name" : "logs-foo-bar", "indices" : [ { "index_name" : ".ds-logs-foo-bar-2025.02.13-000001", ... "index_mode" : "logsdb" }, { "index_name" : ".ds-logs-foo-bar-2025.02.13-000002", ... "index_mode" : "logsdb" } ], ... "index_mode" : "logsdb", } ] } ```
This commit is contained in:
parent
2fa6651a68
commit
47706b505f
11 changed files with 585 additions and 26 deletions
376
docs/reference/indices/get-data-stream.asciidoc
Normal file
376
docs/reference/indices/get-data-stream.asciidoc
Normal file
|
@ -0,0 +1,376 @@
|
|||
[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}/]
|
Loading…
Add table
Add a link
Reference in a new issue