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.

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.3] [DOCS] Reformat flush API docs (#46875) #47232

Merged
merged 1 commit into from
Sep 27, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion docs/reference/index-modules/allocation/delayed.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<synced-flush-api,sync-flushed>>.
requests) which have been automatically <<indices-synced-flush-api,sync-flushed>>.

The allocation of replica shards which become unassigned because a node has
left can be delayed with the `index.unassigned.node_left.delayed_timeout`
Expand Down
136 changes: 105 additions & 31 deletions docs/reference/indices/flush.asciidoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,33 @@
[[indices-flush]]
=== Flush
=== Flush API
++++
<titleabbrev>Flush</titleabbrev>
++++

Flushes one or more indices.

[source,js]
--------------------------------------------------
POST /twitter/_flush
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]


[[flush-api-request]]
==== {api-request-title}

`POST /<index>/flush`

`GET /<index>/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
Expand All @@ -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 <<indices-synced-flush-api>>.
[source,js]
----
POST /_flush
----
// CONSOLE
2 changes: 1 addition & 1 deletion docs/reference/redirects.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -760,7 +760,7 @@ See <<explain-analyze-api>>.

[role="exclude",id="indices-synced-flush"]
=== Synced flush API
See <<synced-flush-api>>.
See <<indices-synced-flush-api>>.

[role="exclude",id="ccs-reduction"]
=== {ccs-cap} reduction
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/upgrade/cluster_restart.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ include::disable-shard-alloc.asciidoc[]
. *Stop indexing and perform a synced flush.*
+
--
Performing a <<synced-flush-api, synced-flush>> speeds up shard
Performing a <<indices-synced-flush-api, synced-flush>> speeds up shard
recovery.

include::synced-flush.asciidoc[]
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/upgrade/rolling_upgrade.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
<<synced-flush-api, synced-flush>>.
<<indices-synced-flush-api, synced-flush>>.

include::synced-flush.asciidoc[]

Expand Down Expand Up @@ -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 <<synced-flush-api,sync-flushed>> might take longer to
Shards that were not <<indices-synced-flush-api,sync-flushed>> might take longer to
recover. You can monitor the recovery status of individual shards by
submitting a <<cat-recovery,`_cat/recovery`>> request:

Expand Down