From 5342168028968971b238ac87965687b67c8cb58b Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 27 Sep 2019 12:27:58 -0400 Subject: [PATCH] [DOCS] Reformat flush API docs (#46875) (#47231) --- .../index-modules/allocation/delayed.asciidoc | 2 +- docs/reference/indices/flush.asciidoc | 138 +++++++++++++----- docs/reference/redirects.asciidoc | 2 +- .../upgrade/cluster_restart.asciidoc | 2 +- .../upgrade/rolling_upgrade.asciidoc | 4 +- 5 files changed, 108 insertions(+), 40 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 149a01d2738c8..627a096907ead 100644 --- a/docs/reference/indices/flush.asciidoc +++ b/docs/reference/indices/flush.asciidoc @@ -1,5 +1,32 @@ [[indices-flush]] -=== Flush +=== Flush API +++++ +Flush +++++ + +Flushes one or more indices. + +[source,console] +-------------------------------------------------- +POST /twitter/_flush +-------------------------------------------------- +// TEST[setup:twitter] + + +[[flush-api-request]] +==== {api-request-title} + +`POST //flush` + +`GET //flush` + +`POST /flush` + +`GET /flush` + + +[[flush-api-desc]] +==== {api-description-title} Flushing an index is the process of making sure that any data that is currently only stored in the <> is also @@ -22,49 +49,90 @@ call the flush API after indexing some documents then a successful response indicates that {es} has flushed all the documents that were indexed before the flush API was called. -[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 flush operation will block until the -flush can be executed if another flush operation is already executing. If set to -`false` then an exception will be thrown on the shard level if another flush -operation is already running. Defaults to `true`. -`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 can be used to force -the generation number of the transaction log to be incremented even if no -uncommitted changes are present. This parameter should be considered 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] -The flush API can be applied to more than one index with a single call, or even -on `_all` the indices. +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] ++ +Defaults to `open`. -[source,js] --------------------------------------------------- -POST kimchy,elasticsearch/_flush +`force`:: ++ +-- +(Optional, boolean) +If `true`, +the request forces a flush +even if there are no changes to commit to the index. +Defaults to `true`. -POST _flush --------------------------------------------------- -// CONSOLE +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,console] +---- +POST /kimchy/_flush +---- +// TEST[s/^/PUT kimchy\n/] + + +[[flush-multi-index]] +===== Flush several indices + +[source,console] +---- +POST /kimchy,elasticsearch/_flush +---- // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/] -[float] -[[synced-flush-api]] -==== Synced Flush +[[flush-api-all-ex]] +===== Flush all indices -See <>. +[source,console] +---- +POST /_flush +---- diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 5617a62d553bc..72bfbc4081977 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="_repositories"] === Snapshot repositories 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: