From a464fd8669a2d468394555e8c24d35ef5ea0ee3a Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 27 Sep 2019 11:42:55 -0400 Subject: [PATCH] [DOCS] Reformat flush API docs (#46875) --- .../index-modules/allocation/delayed.asciidoc | 2 +- docs/reference/indices/flush.asciidoc | 136 ++++++++++++++---- docs/reference/redirects.asciidoc | 2 +- .../upgrade/cluster_restart.asciidoc | 2 +- .../upgrade/rolling_upgrade.asciidoc | 4 +- 5 files changed, 110 insertions(+), 36 deletions(-) diff --git a/docs/reference/index-modules/allocation/delayed.asciidoc b/docs/reference/index-modules/allocation/delayed.asciidoc index c6626a9dec323..ec3f4bff1afb0 100644 --- a/docs/reference/index-modules/allocation/delayed.asciidoc +++ b/docs/reference/index-modules/allocation/delayed.asciidoc @@ -28,7 +28,7 @@ this scenario: If the master had just waited for a few minutes, then the missing shards could have been re-allocated to Node 5 with the minimum of network traffic. This process would be even quicker for idle shards (shards not receiving indexing -requests) which have been automatically <>. +requests) which have been automatically <>. The allocation of replica shards which become unassigned because a node has left can be delayed with the `index.unassigned.node_left.delayed_timeout` diff --git a/docs/reference/indices/flush.asciidoc b/docs/reference/indices/flush.asciidoc index da370dcf50306..750894ff7485e 100644 --- a/docs/reference/indices/flush.asciidoc +++ b/docs/reference/indices/flush.asciidoc @@ -1,5 +1,33 @@ [[indices-flush]] -=== Flush +=== Flush API +++++ +Flush +++++ + +Flushes one or more indices. + +[source,js] +-------------------------------------------------- +POST /twitter/_flush +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + + +[[flush-api-request]] +==== {api-request-title} + +`POST //flush` + +`GET //flush` + +`POST /flush` + +`GET /flush` + + +[[flush-api-desc]] +==== {api-description-title} The flush API allows to flush one or more indices through an API. The flush process of an index makes sure that any data that is currently only @@ -9,47 +37,93 @@ reindexed from the transaction logs after the Lucene indexed is opened. By default, Elasticsearch uses heuristics in order to automatically trigger flushes as required. It is rare for users to need to call the API directly. -[source,js] --------------------------------------------------- -POST twitter/_flush --------------------------------------------------- -// CONSOLE -// TEST[setup:twitter] -[float] -[[flush-parameters]] -==== Request Parameters +[[flush-api-path-params]] +==== {api-path-parms-title} -The flush API accepts the following request parameters: +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] ++ +To flush all indices, +omit this parameter +or use a value of `_all` or `*`. -[horizontal] -`wait_if_ongoing`:: If set to `true`(the default value) the flush operation will -block until the flush can be executed if another flush operation is already executing. -`force`:: Whether a flush should be forced even if it is not necessarily needed i.e. -if no changes will be committed to the index. This is useful if transaction log IDs -should be incremented even if no uncommitted changes are present. -(This setting can be considered as internal) +[[flush-api-query-params]] +==== {api-query-parms-title} -[float] -[[flush-multi-index]] -==== Multi Index +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] ++ +Defaults to `open`. -The flush API can be applied to more than one index with a single call, -or even on `_all` the indices. +`force`:: ++ +-- +(Optional, boolean) +If `true`, +the request forces a flush +even if there are no changes to commit to the index. +Defaults to `true`. + +You can use this parameter +to increment the generation number of the transaction log. + +This parameter is considered internal. +-- + + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +`wait_if_ongoing`:: ++ +-- +(Optional, boolean) +If `true`, +the flush operation blocks until execution +when another flush operation is running. + + +If `false`, +{es} returns an error +if you request a flush +when another flush operation is running. + +Defaults to `true`. +-- + + +[[flush-api-example]] +==== {api-examples-title} + + +[[flush-api-specific-ex]] +===== Flush a specific index [source,js] --------------------------------------------------- -POST kimchy,elasticsearch/_flush +---- +POST /kimchy/_flush +---- +// CONSOLE +// TEST[s/^/PUT kimchy\n/] -POST _flush --------------------------------------------------- + +[[flush-multi-index]] +===== Flush several indices + +[source,js] +---- +POST /kimchy,elasticsearch/_flush +---- // CONSOLE // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/] -[float] -[[synced-flush-api]] -==== Synced Flush +[[flush-api-all-ex]] +===== Flush all indices -See <>. +[source,js] +---- +POST /_flush +---- +// CONSOLE diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 3b6fc45fabce4..303a69fa2c75b 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -760,7 +760,7 @@ See <>. [role="exclude",id="indices-synced-flush"] === Synced flush API -See <>. +See <>. [role="exclude",id="ccs-reduction"] === {ccs-cap} reduction diff --git a/docs/reference/upgrade/cluster_restart.asciidoc b/docs/reference/upgrade/cluster_restart.asciidoc index e6f6446312a38..1c8e3d7f7a58e 100644 --- a/docs/reference/upgrade/cluster_restart.asciidoc +++ b/docs/reference/upgrade/cluster_restart.asciidoc @@ -20,7 +20,7 @@ include::disable-shard-alloc.asciidoc[] . *Stop indexing and perform a synced flush.* + -- -Performing a <> speeds up shard +Performing a <> speeds up shard recovery. include::synced-flush.asciidoc[] diff --git a/docs/reference/upgrade/rolling_upgrade.asciidoc b/docs/reference/upgrade/rolling_upgrade.asciidoc index e90b578265b4f..d28d5726675c3 100644 --- a/docs/reference/upgrade/rolling_upgrade.asciidoc +++ b/docs/reference/upgrade/rolling_upgrade.asciidoc @@ -29,7 +29,7 @@ include::disable-shard-alloc.asciidoc[] -- While you can continue indexing during the upgrade, shard recovery is much faster if you temporarily stop non-essential indexing and perform a -<>. +<>. include::synced-flush.asciidoc[] @@ -132,7 +132,7 @@ As soon as another node is upgraded, the replicas can be assigned and the status will change to `green`. ==================================================== -Shards that were not <> might take longer to +Shards that were not <> might take longer to recover. You can monitor the recovery status of individual shards by submitting a <> request: