diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index 6c54cd5392a..b595904a212 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -2,7 +2,7 @@ == Index APIs Index APIs are used to manage individual indices, -index settings, aliases, mappings, and index templates. +index settings, data streams, aliases, mappings, and index templates. [float] [[index-management]] @@ -31,6 +31,13 @@ index settings, aliases, mappings, and index templates. * <> * <> +[float] +[[data-stream-management]] +=== Data stream management: +* <> +* <> +* <> + [float] [[alias-management]] === Alias management: @@ -154,4 +161,10 @@ include::indices/apis/unfreeze.asciidoc[] include::indices/aliases.asciidoc[] -include::indices/update-settings.asciidoc[] \ No newline at end of file +include::indices/update-settings.asciidoc[] + +include::indices/create-data-stream.asciidoc[] + +include::indices/get-data-stream.asciidoc[] + +include::indices/delete-data-stream.asciidoc[] diff --git a/docs/reference/indices/create-data-stream.asciidoc b/docs/reference/indices/create-data-stream.asciidoc new file mode 100644 index 00000000000..e3a3da3ee0e --- /dev/null +++ b/docs/reference/indices/create-data-stream.asciidoc @@ -0,0 +1,81 @@ +[[indices-create-data-stream]] +=== Create data stream API +++++ +Create data stream +++++ + +Creates a new data stream. + +Data streams provide a convenient way to ingest, search, and manage time series +data. Documents containing time series data may be indexed directly into a data +stream and searched through the data stream. Behind the scenes, data streams +contain one or more hidden backing indices and a generation attribute that +indicates which of the backing indices is the write index, the index into which +documents will be ingested. + +Backing indices are generated with the naming convention +`-zzzzzz` where `zzzzzz` is the six-digit, zero-padded +generation of the data stream. For example, a data stream named +`web-server-logs` with a generation of 34 would have a write index named +`web-server-logs-000034`. While nothing prevents backing indices from being +addressed directly, data streams are integrated with the +<> and +<> to facilitate +the management of the time series data contained in their backing indices. + +[source,console] +-------------------------------------------------- +PUT _data_stream/my-data-stream +{ + "timestamp_field": "@timestamp" +} +-------------------------------------------------- + +//// +[source,console] +----------------------------------- +DELETE /_data_stream/my-data-stream +----------------------------------- +// TEST[continued] +//// + +[[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. + +[[indices-create-data-stream-api-path-params]] +==== {api-path-parms-title} + +``:: ++ +-- +(Required, string) Name of the data stream to create. + +Data stream names must meet the following criteria: + +- Lowercase only +- Cannot include `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character), +`,`, `#`, `:` +- Cannot start with `-`, `_`, `+`, `.` +- Cannot be `.` or `..` +- Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters +will count towards the 255 limit faster) +-- + +[[indices-create-data-stream-api-request-body]] +==== {api-request-body-title} + +`timestamp_field`:: +(Required, string) The name of the timestamp field. This field must be present +in all documents indexed into the data stream and must be of type +<> or <>. + diff --git a/docs/reference/indices/delete-data-stream.asciidoc b/docs/reference/indices/delete-data-stream.asciidoc new file mode 100644 index 00000000000..2a926130999 --- /dev/null +++ b/docs/reference/indices/delete-data-stream.asciidoc @@ -0,0 +1,36 @@ +[[indices-delete-data-stream]] +=== Delete data stream API +++++ +Delete data stream +++++ + +Deletes an existing data stream along with its backing indices. + +//// +[source,console] +----------------------------------- +PUT /_data_stream/my-data-stream +{ + "timestamp_field" : "@timestamp" +} +----------------------------------- +// TESTSETUP +//// + +[source,console] +-------------------------------------------------- +DELETE _data_stream/my-data-stream +-------------------------------------------------- + + +[[delete-data-stream-api-request]] +==== {api-request-title} + +`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. diff --git a/docs/reference/indices/get-data-stream.asciidoc b/docs/reference/indices/get-data-stream.asciidoc new file mode 100644 index 00000000000..07f6882a9e1 --- /dev/null +++ b/docs/reference/indices/get-data-stream.asciidoc @@ -0,0 +1,91 @@ +[[indices-get-data-stream]] +=== Get data stream API +++++ +Get data stream +++++ + +Returns information about one or more data streams. + +//// +[source,console] +----------------------------------- +PUT /_data_stream/my-data-stream +{ + "timestamp_field" : "@timestamp" +} +----------------------------------- +// TESTSETUP +//// + +//// +[source,console] +----------------------------------- +DELETE /_data_stream/my-data-stream +----------------------------------- +// TEARDOWN +//// + +[source,console] +-------------------------------------------------- +GET _data_streams/my-data-stream +-------------------------------------------------- +// TEST[skip_shard_failures] + +[[get-data-stream-api-request]] +==== {api-request-title} + +`GET _data_streams/` + + +[[get-data-stream-api-path-params]] +==== {api-path-parms-title} + +``:: ++ +-- +(Required, string) Name or wildcard expression of the data stream(s) to +retrieve. +-- + +[[get-data-stream-api-example]] +==== {api-examples-title} + +[[get-data-stream-basic-example]] +===== Basic example + +[source,console] +-------------------------------------------------- +GET _data_streams/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> + { + "index_name" : "my-data-stream-000001", + "index_uuid" : "DXAE-xcCQTKF93bMm9iawA" + }, + { + "index_name" : "my-data-stream-000002", + "index_uuid" : "Wzxq0VhsQKyPxHhaK3WYAg" + } + ], + "generation" : 2 <4> + } +] +-------------------------------------------------- +// TESTRESPONSE[skip:unable to assert responses with top level array] + +<1> Name of the data stream +<2> The name of the timestamp field for the data stream +<3> List of backing indices +<4> Current generation for the data stream + diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 2fe44ac964c..376ae6310f5 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -611,7 +611,8 @@ See <> and <>. [role="exclude",id="data-streams"] === Data stream APIs -coming::[7.x] +See <>, <>, and +<>. [role="exclude",id="cat-transform"] === cat transform API