Browse Source

[DOCS] Add get and delete steps to data stream setup tutorial (#58068)

Adds corresponding steps for the get and delete data stream APIs to the
data stream setup tutorial. Also provides some guidance on how to
determine the current write index for a data stream.
James Rodewig 5 years ago
parent
commit
9aa87fe2d7
1 changed files with 112 additions and 2 deletions
  1. 112 2
      docs/reference/data-streams/set-up-a-data-stream.asciidoc

+ 112 - 2
docs/reference/data-streams/set-up-a-data-stream.asciidoc

@@ -7,10 +7,14 @@ To set up a data stream, follow these steps:
 . <<configure-a-data-stream-ilm-policy>>.
 . <<create-a-data-stream-template>>.
 . <<create-a-data-stream>>.
+. <<get-info-about-a-data-stream> to verify it exists.
 
 After you set up a data stream, you can <<use-a-data-stream, use the data
 stream>> for indexing, searches, and other supported operations.
 
+If you no longer need it, you can <<delete-a-data-stream,delete a data stream>>
+and its backing indices.
+
 [discrete]
 [[data-stream-prereqs]]
 === Prerequisites
@@ -107,7 +111,7 @@ Composable templates for data streams must contain:
   timestamp field specified in the `timestamp_field` property.
 
 * If you intend to use {ilm-init}, you must specify the
-  <<configure-a-data-stream-ilm-policy,lifecycle policy>> in the 
+  <<configure-a-data-stream-ilm-policy,lifecycle policy>> in the
   `index.lifecycle.name` setting.
 
 You can also specify other mappings and settings you'd like to apply to the
@@ -240,4 +244,110 @@ DELETE /_index_template/logs_data_stream
 DELETE /_ilm/policy/logs_policy
 ----
 // TEST[continued]
-////
+////
+
+[discrete]
+[[get-info-about-a-data-stream]]
+=== Get information about a data stream
+
+You can use the <<indices-get-data-stream,get data stream API>> to get
+information about one or more data streams, including:
+
+* The timestamp field
+* The current backing indices, which is returned as an array. The last item in
+  the array contains information about the stream's current write index.
+* The current generation
+
+This is also handy way to verify that a recently created data stream exists.
+
+.*Example*
+[%collapsible]
+====
+The following get data stream API request retrieves information about any data
+streams starting with `logs`.
+
+[source,console]
+----
+GET /_data_stream/logs*
+----
+// TEST[skip: shard failures]
+
+The API returns the following response, which includes information about the
+`logs` data stream. Note the `indices` property contains an array of the
+stream's current backing indices. The last item in this array contains
+information for the `logs` stream's write index, `.ds-logs-000002`.
+
+[source,console-result]
+----
+[
+  {
+    "name": "logs",
+    "timestamp_field": "@timestamp",
+    "indices": [
+      {
+        "index_name": ".ds-logs-000001",
+        "index_uuid": "DXAE-xcCQTKF93bMm9iawA"
+      },
+      {
+        "index_name": ".ds-logs-000002",
+        "index_uuid": "Wzxq0VhsQKyPxHhaK3WYAg"
+      }
+    ],
+    "generation": 2
+  }
+]
+----
+// TESTRESPONSE[skip:unable to assert responses with top level array]
+====
+
+[discrete]
+[[delete-a-data-stream]]
+=== Delete a data stream
+
+You can use the <<indices-delete-data-stream,delete data stream API>> to delete
+a data stream and its backing indices.
+
+.*Example*
+[%collapsible]
+====
+The following delete data stream API request deletes the `logs` data stream. This
+request also deletes the stream's backing indices and any data they contain.
+
+////
+[source,console]
+----
+PUT /_index_template/logs_data_stream
+{
+  "index_patterns": [ "logs*" ],
+  "data_stream": {
+    "timestamp_field": "@timestamp"
+  },
+  "template": {
+    "mappings": {
+      "properties": {
+        "@timestamp": {
+          "type": "date"
+        }
+      }
+    }
+  }
+}
+
+PUT /_data_stream/logs
+----
+////
+
+[source,console]
+----
+DELETE /_data_stream/logs
+----
+// TEST[continued]
+====
+
+////
+[source,console]
+----
+DELETE /_index_template/logs_data_stream
+----
+// TEST[continued]
+////