Docs for data stream REST APIs

This commit is contained in:
Dan Hermann 2020-05-15 09:37:45 -05:00 committed by GitHub
parent 5e09762a27
commit 2a21d4d976
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 225 additions and 3 deletions

View File

@ -2,7 +2,7 @@
== Index APIs == Index APIs
Index APIs are used to manage individual indices, 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] [float]
[[index-management]] [[index-management]]
@ -31,6 +31,13 @@ index settings, aliases, mappings, and index templates.
* <<indices-get-field-mapping>> * <<indices-get-field-mapping>>
* <<indices-types-exists>> * <<indices-types-exists>>
[float]
[[data-stream-management]]
=== Data stream management:
* <<indices-create-data-stream>>
* <<indices-delete-data-stream>>
* <<indices-get-data-stream>>
[float] [float]
[[alias-management]] [[alias-management]]
=== Alias management: === Alias management:
@ -154,4 +161,10 @@ include::indices/apis/unfreeze.asciidoc[]
include::indices/aliases.asciidoc[] include::indices/aliases.asciidoc[]
include::indices/update-settings.asciidoc[] include::indices/update-settings.asciidoc[]
include::indices/create-data-stream.asciidoc[]
include::indices/get-data-stream.asciidoc[]
include::indices/delete-data-stream.asciidoc[]

View File

@ -0,0 +1,81 @@
[[indices-create-data-stream]]
=== Create data stream API
++++
<titleabbrev>Create data stream</titleabbrev>
++++
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
`<data-stream-name>-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
<<indices-rollover-index, rollover index API>> and
<<index-lifecycle-management, index lifecycle management (ILM)>> 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/<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}
`<data-stream>`::
+
--
(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
<<date, `date`>> or <<date_nanos, `date_nanos`>>.

View File

@ -0,0 +1,36 @@
[[indices-delete-data-stream]]
=== Delete data stream API
++++
<titleabbrev>Delete data stream</titleabbrev>
++++
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/<data-stream>`
[[delete-data-stream-api-path-params]]
==== {api-path-parms-title}
`<data-stream>`::
(Required, string) Name or wildcard expression of data stream(s) to delete.

View File

@ -0,0 +1,91 @@
[[indices-get-data-stream]]
=== Get data stream API
++++
<titleabbrev>Get data stream</titleabbrev>
++++
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/<data-stream>`
[[get-data-stream-api-path-params]]
==== {api-path-parms-title}
`<data-stream>`::
+
--
(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

View File

@ -611,7 +611,8 @@ See <<ccs-gateway-seed-nodes>> and <<ccs-min-roundtrips>>.
[role="exclude",id="data-streams"] [role="exclude",id="data-streams"]
=== Data stream APIs === Data stream APIs
coming::[7.x] See <<indices-create-data-stream>>, <<indices-get-data-stream>>, and
<<indices-delete-data-stream>>.
[role="exclude",id="cat-transform"] [role="exclude",id="cat-transform"]
=== cat transform API === cat transform API