From 9ba1b1d067af5c6f779ebf52f46c83057b3eff06 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 18 Jun 2020 10:59:12 -0400 Subject: [PATCH] [DOCS] Reformat data stream API docs (#58322) (#58334) --- .../data-streams/data-stream-apis.asciidoc | 14 +++--- .../indices/create-data-stream.asciidoc | 31 +++++------- .../indices/delete-data-stream.asciidoc | 25 +++++----- .../indices/get-data-stream.asciidoc | 47 +++++++++---------- 4 files changed, 55 insertions(+), 62 deletions(-) diff --git a/docs/reference/data-streams/data-stream-apis.asciidoc b/docs/reference/data-streams/data-stream-apis.asciidoc index c1cc2414c0b..a19a4bc7877 100644 --- a/docs/reference/data-streams/data-stream-apis.asciidoc +++ b/docs/reference/data-streams/data-stream-apis.asciidoc @@ -1,14 +1,16 @@ [[data-stream-apis]] == Data stream APIs -The following APIs are available for managing data streams: +The following APIs are available for managing <>: -* To get information about data streams, use the <>. -* To delete data streams, use the <>. -* To manually create a data stream, use the <>. +* <> +* <> +* <> + +For concepts and tutorials, see <>. include::{es-repo-dir}/indices/create-data-stream.asciidoc[] -include::{es-repo-dir}/indices/get-data-stream.asciidoc[] +include::{es-repo-dir}/indices/delete-data-stream.asciidoc[] -include::{es-repo-dir}/indices/delete-data-stream.asciidoc[] \ No newline at end of file +include::{es-repo-dir}/indices/get-data-stream.asciidoc[] diff --git a/docs/reference/indices/create-data-stream.asciidoc b/docs/reference/indices/create-data-stream.asciidoc index 37474321e2a..f2f5522c077 100644 --- a/docs/reference/indices/create-data-stream.asciidoc +++ b/docs/reference/indices/create-data-stream.asciidoc @@ -4,14 +4,15 @@ Create data stream ++++ -Creates a new data stream. +Creates a new <>. -A data stream can only be created if the namespace it targets has a composable -index template with a `data_stream` definition. +Data streams require an associated <>. +See <>. +//// [source,console] ------------------------------------ -PUT _index_template/template +---- +PUT /_index_template/template { "index_patterns": ["my-data-stream*"], "template": { @@ -27,13 +28,13 @@ PUT _index_template/template "timestamp_field": "@timestamp" } } ------------------------------------ -// TEST +---- +//// [source,console] --------------------------------------------------- -PUT _data_stream/my-data-stream --------------------------------------------------- +---- +PUT /_data_stream/my-data-stream +---- // TEST[continued] //// @@ -48,15 +49,7 @@ DELETE /_index_template/template [[indices-create-data-stream-request]] ==== {api-request-title} -`PUT _data_stream/` - -[[indices-create-data-stream-desc]] -==== {api-description-title} -You can use the create data stream API to add a new data stream to an {es} -cluster. When creating a data stream, you must specify the following: - -* The name of the data stream -* The name of the timestamp field. +`PUT /_data_stream/` [[indices-create-data-stream-api-path-params]] ==== {api-path-parms-title} diff --git a/docs/reference/indices/delete-data-stream.asciidoc b/docs/reference/indices/delete-data-stream.asciidoc index 939ed4df92a..c7bbee4537e 100644 --- a/docs/reference/indices/delete-data-stream.asciidoc +++ b/docs/reference/indices/delete-data-stream.asciidoc @@ -4,12 +4,13 @@ Delete data stream ++++ -Deletes an existing data stream along with its backing indices. +Deletes one or more <> and their backing +indices. See <>. //// [source,console] ------------------------------------ -PUT _index_template/template +---- +PUT /_index_template/template { "index_patterns": ["my-data-stream*"], "template": { @@ -27,31 +28,33 @@ PUT _index_template/template } PUT /_data_stream/my-data-stream ------------------------------------ +---- // TESTSETUP //// [source,console] --------------------------------------------------- -DELETE _data_stream/my-data-stream --------------------------------------------------- +---- +DELETE /_data_stream/my-data-stream +---- //// [source,console] ------------------------------------ +---- DELETE /_index_template/template ------------------------------------ +---- // TEST[continued] //// [[delete-data-stream-api-request]] ==== {api-request-title} -`DELETE _data_stream/` +`DELETE /_data_stream/` [[delete-data-stream-api-path-params]] ==== {api-path-parms-title} ``:: -(Required, string) Name or wildcard expression of data stream(s) to delete. +(Required, string) +Name of the data stream to delete. +Wildcard (`*`) expressions are supported. diff --git a/docs/reference/indices/get-data-stream.asciidoc b/docs/reference/indices/get-data-stream.asciidoc index ba97fa27a17..d61683548c4 100644 --- a/docs/reference/indices/get-data-stream.asciidoc +++ b/docs/reference/indices/get-data-stream.asciidoc @@ -4,11 +4,12 @@ Get data stream ++++ -Returns information about one or more data streams. +Retrieves information about one or more <>. +See <>. //// [source,console] ------------------------------------ +---- PUT _index_template/template { "index_patterns": ["my-data-stream*"], @@ -27,63 +28,57 @@ PUT _index_template/template } PUT /_data_stream/my-data-stream ------------------------------------ +---- // TESTSETUP //// //// [source,console] ------------------------------------ +---- DELETE /_data_stream/my-data-stream DELETE /_index_template/template ------------------------------------ +---- // TEARDOWN //// [source,console] --------------------------------------------------- -GET _data_stream/my-data-stream --------------------------------------------------- +---- +GET /_data_stream/my-data-stream +---- // TEST[skip_shard_failures] [[get-data-stream-api-request]] ==== {api-request-title} -`GET _data_stream/` - +`GET /_data_stream/` [[get-data-stream-api-path-params]] ==== {api-path-parms-title} ``:: -+ --- -(Required, string) Name or wildcard expression of the data stream(s) to -retrieve. --- +(Required, string) +Name of the data stream to retrieve. +Wildcard (`*`) expressions are supported. [[get-data-stream-api-example]] ==== {api-examples-title} -[[get-data-stream-basic-example]] -===== Basic example - [source,console] --------------------------------------------------- +---- GET _data_stream/my-data-stream* --------------------------------------------------- +---- // TEST[continued] // TEST[skip_shard_failures] The API returns the following response: [source,console-result] --------------------------------------------------- +---- [ { - "name" : "my-data-stream", <1> - "timestamp_field" : "@timestamp", <2> - "indices" : [ <3> + "name" : "my-data-stream", <1> + "timestamp_field" : "@timestamp", <2> + "indices" : [ <3> { "index_name" : ".ds-my-data-stream-000001", "index_uuid" : "DXAE-xcCQTKF93bMm9iawA" @@ -93,10 +88,10 @@ The API returns the following response: "index_uuid" : "Wzxq0VhsQKyPxHhaK3WYAg" } ], - "generation" : 2 <4> + "generation" : 2 <4> } ] --------------------------------------------------- +---- // TESTRESPONSE[skip:unable to assert responses with top level array] <1> Name of the data stream