Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.x] [DOCS] Document open requests for data streams (#58615) #58621

Merged
merged 5 commits into from
Jul 1, 2020
Merged

[7.x] [DOCS] Document open requests for data streams (#58615) #58621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ccd51cf
[DOCS] Document open requests for data streams (#58615)
jrodewig Jun 26, 2020
39b895f
Merge branch '7.x' into backport__7x
elasticmachine Jun 29, 2020
14b6562
Merge branch '7.x' into backport__7x
jrodewig Jun 30, 2020
9390275
[DOCS] Make `<target>` defs consistent
jrodewig Jun 30, 2020
3bd8ef8
Merge branch '7.x' into backport__7x
elasticmachine Jul 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 92 additions & 14 deletions docs/reference/data-streams/use-a-data-stream.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ the following:
* <<add-documents-to-a-data-stream>>
* <<search-a-data-stream>>
* <<manually-roll-over-a-data-stream>>
* <<open-closed-backing-indices>>
* <<reindex-with-a-data-stream>>
* <<update-delete-docs-in-a-data-stream>>
* <<update-delete-docs-in-a-backing-index>>
Expand Down Expand Up @@ -236,15 +237,92 @@ rollover request for the `logs` data stream.
[source,console]
----
POST /logs/_rollover/
{
"conditions": {
"max_docs": "1"
}
}
----
// TEST[continued]
====

[discrete]
[[open-closed-backing-indices]]
=== Open closed backing indices

You may <<indices-close,close>> one or more of a data stream's backing indices
as part of its {ilm-init} lifecycle or another workflow. A closed backing index
cannot be searched, even for searches targeting its data stream. You also can't
<<update-delete-docs-in-a-data-stream,update or delete documents>> in a closed
index.

You can re-open individual backing indices by sending an
<<indices-open-close,open request>> directly to the index.

You also can conveniently re-open all closed backing indices for a data stream
by sending an open request directly to the stream.

.*Example*
[%collapsible]
====
////
[source,console]
----
POST /logs/_rollover/

POST /.ds-logs-000001,.ds-logs-000002/_close/
----
// TEST[continued]
////

The following <<cat-indices,cat indices>> API request retrieves the status for
the `logs` data stream's backing indices.

[source,console]
----
GET /_cat/indices/logs?v&s=index&h=index,status
----
// TEST[continued]

The API returns the following response. The response indicates the `logs` data
stream contains two closed backing indices: `.ds-logs-000001` and
`.ds-logs-000002`.

[source,txt]
----
index status
.ds-logs-000001 close
.ds-logs-000002 close
.ds-logs-000003 open
----
// TESTRESPONSE[non_json]

The following <<indices-open-close,open API>> request re-opens any closed
backing indices for the `logs` data stream, including `.ds-logs-000001` and
`.ds-logs-000002`.

[source,console]
----
POST /logs/_open/
----
// TEST[continued]

You can resubmit the original cat indices API request to verify the
`.ds-logs-000001` and `.ds-logs-000002` backing indices were re-opened.

[source,console]
----
GET /_cat/indices/logs?v&s=index&h=index,status
----
// TEST[continued]

The API returns the following response.

[source,txt]
----
index status
.ds-logs-000001 open
.ds-logs-000002 open
.ds-logs-000003 open
----
// TESTRESPONSE[non_json]
====

[discrete]
[[reindex-with-a-data-stream]]
=== Reindex with a data stream
Expand Down Expand Up @@ -502,8 +580,8 @@ information for any documents matching the search.
"took": 20,
"timed_out": false,
"_shards": {
"total": 2,
"successful": 2,
"total": 3,
"successful": 3,
"skipped": 0,
"failed": 0
},
Expand All @@ -515,7 +593,7 @@ information for any documents matching the search.
"max_score": 0.2876821,
"hits": [
{
"_index": ".ds-logs-000002", <1>
"_index": ".ds-logs-000003", <1>
"_type": "_doc",
"_id": "bfspvnIBr7VVZlfp2lqX", <2>
"_seq_no": 8, <3>
Expand Down Expand Up @@ -552,15 +630,15 @@ document. To prevent an accidental overwrite, this request must include valid
====
The following index API request updates an existing document in the `logs` data
stream. The request targets document ID `bfspvnIBr7VVZlfp2lqX` in the
`.ds-logs-000002` backing index.
`.ds-logs-000003` backing index.

The request also includes the current sequence number and primary term in the
respective `if_seq_no` and `if_primary_term` query parameters. The request body
contains a new JSON source for the document.

[source,console]
----
PUT /.ds-logs-000002/_doc/bfspvnIBr7VVZlfp2lqX?if_seq_no=8&if_primary_term=1
PUT /.ds-logs-000003/_doc/bfspvnIBr7VVZlfp2lqX?if_seq_no=8&if_primary_term=1
{
"@timestamp": "2020-12-07T11:06:07.000Z",
"user": {
Expand All @@ -580,11 +658,11 @@ requests do not require a sequence number or primary term.
====
The following index API request deletes an existing document in the `logs` data
stream. The request targets document ID `bfspvnIBr7VVZlfp2lqX` in the
`.ds-logs-000002` backing index.
`.ds-logs-000003` backing index.

[source,console]
----
DELETE /.ds-logs-000002/_doc/bfspvnIBr7VVZlfp2lqX
DELETE /.ds-logs-000003/_doc/bfspvnIBr7VVZlfp2lqX
----
// TEST[continued]
====
Expand Down Expand Up @@ -618,14 +696,14 @@ The following bulk API request uses an `index` action to update an existing
document in the `logs` data stream.

The `index` action targets document ID `bfspvnIBr7VVZlfp2lqX` in the
`.ds-logs-000002` backing index. The action also includes the current sequence
`.ds-logs-000003` backing index. The action also includes the current sequence
number and primary term in the respective `if_seq_no` and `if_primary_term`
parameters.

[source,console]
----
PUT /_bulk?refresh
{ "index": { "_index": ".ds-logs-000002", "_id": "bfspvnIBr7VVZlfp2lqX", "if_seq_no": 8, "if_primary_term": 1 } }
{ "index": { "_index": ".ds-logs-000003", "_id": "bfspvnIBr7VVZlfp2lqX", "if_seq_no": 8, "if_primary_term": 1 } }
{ "@timestamp": "2020-12-07T11:06:07.000Z", "user": { "id": "8a4f500d" }, "message": "Login successful" }
----
// TEST[continued]
Expand Down
20 changes: 13 additions & 7 deletions docs/reference/indices/open-close.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
<titleabbrev>Open index</titleabbrev>
++++

Opens a closed index.
Opens a closed index. For data streams, the API
opens any closed backing indices.

[source,console]
--------------------------------------------------
Expand All @@ -17,13 +18,14 @@ POST /twitter/_open
[[open-index-api-request]]
==== {api-request-title}

`POST /<index>/_open`
`POST /<target>/_open`


[[open-index-api-desc]]
==== {api-description-title}

You use the open index API to re-open closed indices.
You can use the open index API to re-open closed indices. If the request targets
a data stream, the request re-opens any of the stream's closed backing indices.

// tag::closed-index[]

Expand Down Expand Up @@ -80,10 +82,14 @@ index creation applies to the `_open` and `_close` index actions as well.
[[open-index-api-path-params]]
==== {api-path-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
`<target>`::
(Optional, string)
Comma-separated list or wildcard (`*`) expression of data streams, indices, and
index aliases used to limit the request.
+
To open all indices, use `_all` or `*`.
To disallow the opening of indices with `_all` or wildcard expressions,
To target all data streams and indices, use `_all` or `*`.
+
To disallow use of `_all` or wildcard expressions,
change the `action.destructive_requires_name` cluster setting to `true`.
You can update this setting in the `elasticsearch.yml` file
or using the <<cluster-update-settings,cluster update settings>> API.
Expand All @@ -110,7 +116,7 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
[[open-index-api-example]]
==== {api-examples-title}

A closed index can be re-opened like this:
The following request re-opens a closed index named `my_index`.

[source,console]
--------------------------------------------------
Expand Down