From 7a8da9daa3f18c3967466c24ba5fe8e3ab2adf25 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 1 Jul 2020 11:22:45 -0400 Subject: [PATCH] [DOCS] Document open requests for data streams (#58615) (#58621) Adds an open API example to the data streams docs. Also updates the existing open API docs to make them aware of data streams. --- .../data-streams/use-a-data-stream.asciidoc | 106 +++++++++++++++--- docs/reference/indices/open-close.asciidoc | 20 ++-- 2 files changed, 105 insertions(+), 21 deletions(-) diff --git a/docs/reference/data-streams/use-a-data-stream.asciidoc b/docs/reference/data-streams/use-a-data-stream.asciidoc index dd54945b1e095..ac1c1e5341d3e 100644 --- a/docs/reference/data-streams/use-a-data-stream.asciidoc +++ b/docs/reference/data-streams/use-a-data-stream.asciidoc @@ -7,6 +7,7 @@ the following: * <> * <> * <> +* <> * <> * <> * <> @@ -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 <> 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 +<> in a closed +index. + +You can re-open individual backing indices by sending an +<> 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 <> 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 <> 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 @@ -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 }, @@ -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> @@ -552,7 +630,7 @@ 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 @@ -560,7 +638,7 @@ 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": { @@ -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] ==== @@ -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] diff --git a/docs/reference/indices/open-close.asciidoc b/docs/reference/indices/open-close.asciidoc index d2a0ca957af6f..660e56771c24a 100644 --- a/docs/reference/indices/open-close.asciidoc +++ b/docs/reference/indices/open-close.asciidoc @@ -4,7 +4,8 @@ Open index ++++ -Opens a closed index. +Opens a closed index. For data streams, the API +opens any closed backing indices. [source,console] -------------------------------------------------- @@ -17,13 +18,14 @@ POST /twitter/_open [[open-index-api-request]] ==== {api-request-title} -`POST //_open` +`POST //_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[] @@ -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] +``:: +(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 <> API. @@ -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] --------------------------------------------------