From ccf3fa1f35676938f2c8f71f36921ccdc5c035bd Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 23 Aug 2019 13:08:00 -0400 Subject: [PATCH 1/3] [DOCS] Reformat open index API docs --- docs/reference/indices/open-close.asciidoc | 126 +++++++++++++-------- 1 file changed, 78 insertions(+), 48 deletions(-) diff --git a/docs/reference/indices/open-close.asciidoc b/docs/reference/indices/open-close.asciidoc index efbd289758a6b..6a99509cd1471 100644 --- a/docs/reference/indices/open-close.asciidoc +++ b/docs/reference/indices/open-close.asciidoc @@ -1,8 +1,32 @@ [[indices-open-close]] -=== Open / Close Index API +=== Open index API +++++ +Open index +++++ -The open and close index APIs allow to close an index, and later on -opening it. +Opens a closed index. + +[source,js] +-------------------------------------------------- +POST /twitter/_open +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] +// TEST[s/^/POST \/twitter\/_close\n/] + + +[[open-index-api-request]] +==== {api-request-title} + +`POST //_open` + + +[[open-index-api-desc]] +==== {api-description-title} + +You can use the open index API to re-open a closed index. + +// tag:closed-index A closed index is blocked for read/write operations and does not allow all operations that opened indices allow. It is not possible to index @@ -18,34 +42,61 @@ data of opened/closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times. -The REST endpoint is `/{index}/_close` and `/{index}/_open`. +It is possible to open and close multiple indices. An error will be thrown +if the request explicitly refers to a missing index. This behaviour can be +disabled using the `ignore_unavailable=true` parameter. -The following example shows how to close an index: +All indices can be opened or closed at once using `_all` as the index name +or specifying patterns that identify them all (e.g. `*`). -[source,js] --------------------------------------------------- -POST /my_index/_close --------------------------------------------------- -// CONSOLE -// TEST[s/^/PUT my_index\n/] +Identifying indices via wildcards or `_all` can be disabled by setting the +`action.destructive_requires_name` flag in the config file to `true`. +This setting can also be changed via the cluster update settings api. -This will return the following response: +Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be disabled via the cluster settings +API by setting `cluster.indices.close.enable` to `false`. The default is `true`. -[source,js] --------------------------------------------------- -{ - "acknowledged" : true, - "shards_acknowledged" : true, - "indices" : { - "my_index" : { - "closed" : true - } - } -} --------------------------------------------------- -// TESTRESPONSE +===== Wait For active shards -A closed index can be reopened like this: +Because opening or closing an index allocates its shards, the +<> setting on +index creation applies to the `_open` and `_close` index actions as well. + +// end:closed-index + + +[[open-index-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] ++ +To open all indices, use `_all` or `*`. +To disallow the opening of indices with `_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. + + +[[open-index-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] ++ +Defaults to `closed`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[open-index-api-example]] +==== {api-examples-title} + +A closed index can be re-opened like this: [source,js] -------------------------------------------------- @@ -54,7 +105,7 @@ POST /my_index/_open // CONSOLE // TEST[s/^/PUT my_index\nPOST my_index\/_close\n/] -which will yield the following response: +The API returns the following response: [source,js] -------------------------------------------------- @@ -64,24 +115,3 @@ which will yield the following response: } -------------------------------------------------- // TESTRESPONSE - -It is possible to open and close multiple indices. An error will be thrown -if the request explicitly refers to a missing index. This behaviour can be -disabled using the `ignore_unavailable=true` parameter. - -All indices can be opened or closed at once using `_all` as the index name -or specifying patterns that identify them all (e.g. `*`). - -Identifying indices via wildcards or `_all` can be disabled by setting the -`action.destructive_requires_name` flag in the config file to `true`. -This setting can also be changed via the cluster update settings api. - -Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be disabled via the cluster settings -API by setting `cluster.indices.close.enable` to `false`. The default is `true`. - -[float] -==== Wait For Active Shards - -Because opening or closing an index allocates its shards, the -<> setting on -index creation applies to the `_open` and `_close` index actions as well. From 7cc1511494a52ab11e9e898fd903cac5c365899e Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 27 Aug 2019 08:58:30 -0400 Subject: [PATCH 2/3] Reword error sentence --- docs/reference/indices/open-close.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/indices/open-close.asciidoc b/docs/reference/indices/open-close.asciidoc index 6a99509cd1471..8e2f1f0c6aec4 100644 --- a/docs/reference/indices/open-close.asciidoc +++ b/docs/reference/indices/open-close.asciidoc @@ -42,7 +42,7 @@ data of opened/closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times. -It is possible to open and close multiple indices. An error will be thrown +It is possible to open and close multiple indices. An error is thrown if the request explicitly refers to a missing index. This behaviour can be disabled using the `ignore_unavailable=true` parameter. From c6736f9e492a2fcd9e14d377a7011af1115abaa6 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 27 Aug 2019 09:00:31 -0400 Subject: [PATCH 3/3] Reword --- docs/reference/indices/open-close.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/indices/open-close.asciidoc b/docs/reference/indices/open-close.asciidoc index 8e2f1f0c6aec4..c122617470e2f 100644 --- a/docs/reference/indices/open-close.asciidoc +++ b/docs/reference/indices/open-close.asciidoc @@ -24,7 +24,7 @@ POST /twitter/_open [[open-index-api-desc]] ==== {api-description-title} -You can use the open index API to re-open a closed index. +You use the open index API to re-open closed indices. // tag:closed-index @@ -42,7 +42,7 @@ data of opened/closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times. -It is possible to open and close multiple indices. An error is thrown +You can open and close multiple indices. An error is thrown if the request explicitly refers to a missing index. This behaviour can be disabled using the `ignore_unavailable=true` parameter.