diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndicesClient.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndicesClient.java index 42791b719c4e2..fc41b75590967 100644 --- a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndicesClient.java +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndicesClient.java @@ -569,7 +569,7 @@ public void flushAsync(FlushRequest flushRequest, RequestOptions options, Action /** * Initiate a synced flush manually using the synced flush API. - * See + * See * Synced flush API on elastic.co * @param syncedFlushRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized @@ -583,7 +583,7 @@ public SyncedFlushResponse flushSynced(SyncedFlushRequest syncedFlushRequest, Re /** * Asynchronously initiate a synced flush manually using the synced flush API. - * See + * See * Synced flush API on elastic.co * @param syncedFlushRequest the request * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index beb26b76d6cdc..d066478caedee 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -68,6 +68,7 @@ index settings, aliases, mappings, and index templates. * <> * <> * <> +* <> * <> include::indices/create-index.asciidoc[] @@ -136,6 +137,8 @@ include::indices/clearcache.asciidoc[] include::indices/flush.asciidoc[] +include::indices/synced-flush.asciidoc[] + include::indices/refresh.asciidoc[] include::indices/forcemerge.asciidoc[] diff --git a/docs/reference/indices/flush.asciidoc b/docs/reference/indices/flush.asciidoc index 29a5b6d4d28a4..da370dcf50306 100644 --- a/docs/reference/indices/flush.asciidoc +++ b/docs/reference/indices/flush.asciidoc @@ -47,198 +47,9 @@ POST _flush // CONSOLE // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/] -[[synced-flush-api]] -==== Synced Flush - -Elasticsearch tracks the indexing activity of each shard. Shards that have not -received any indexing operations for 5 minutes are automatically marked as inactive. This presents -an opportunity for Elasticsearch to reduce shard resources and also perform -a special kind of flush, called `synced flush`. A synced flush performs a normal flush, then adds -a generated unique marker (sync_id) to all shards. - -Since the sync id marker was added when there were no ongoing indexing operations, it can -be used as a quick way to check if the two shards' lucene indices are identical. This quick sync id -comparison (if present) is used during recovery or restarts to skip the first and -most costly phase of the process. In that case, no segment files need to be copied and -the transaction log replay phase of the recovery can start immediately. Note that since the sync id -marker was applied together with a flush, it is very likely that the transaction log will be empty, -speeding up recoveries even more. - -This is particularly useful for use cases having lots of indices which are -never or very rarely updated, such as time based data. This use case typically generates lots of indices whose -recovery without the synced flush marker would take a long time. - -To check whether a shard has a marker or not, look for the `commit` section of shard stats returned by -the <> API: - -[source,sh] --------------------------------------------------- -GET twitter/_stats?filter_path=**.commit&level=shards <1> --------------------------------------------------- -// CONSOLE -// TEST[s/^/PUT twitter\nPOST twitter\/_flush\/synced\n/] -<1> `filter_path` is used to reduce the verbosity of the response, but is entirely optional - - -which returns something similar to: - -[source,js] --------------------------------------------------- -{ - "indices": { - "twitter": { - "shards": { - "0": [ - { - "commit" : { - "id" : "3M3zkw2GHMo2Y4h4/KFKCg==", - "generation" : 3, - "user_data" : { - "translog_uuid" : "hnOG3xFcTDeoI_kvvvOdNA", - "history_uuid" : "XP7KDJGiS1a2fHYiFL5TXQ", - "local_checkpoint" : "-1", - "translog_generation" : "2", - "max_seq_no" : "-1", - "sync_id" : "AVvFY-071siAOuFGEO9P", <1> - "max_unsafe_auto_id_timestamp" : "-1", - "min_retained_seq_no" : "0" - }, - "num_docs" : 0 - } - } - ] - } - } - } -} --------------------------------------------------- -// TESTRESPONSE[s/"id" : "3M3zkw2GHMo2Y4h4\/KFKCg=="/"id": $body.indices.twitter.shards.0.0.commit.id/] -// TESTRESPONSE[s/"translog_uuid" : "hnOG3xFcTDeoI_kvvvOdNA"/"translog_uuid": $body.indices.twitter.shards.0.0.commit.user_data.translog_uuid/] -// TESTRESPONSE[s/"history_uuid" : "XP7KDJGiS1a2fHYiFL5TXQ"/"history_uuid": $body.indices.twitter.shards.0.0.commit.user_data.history_uuid/] -// TESTRESPONSE[s/"sync_id" : "AVvFY-071siAOuFGEO9P"/"sync_id": $body.indices.twitter.shards.0.0.commit.user_data.sync_id/] -<1> the `sync id` marker [float] -==== Synced Flush API - -The Synced Flush API allows an administrator to initiate a synced flush manually. This can be particularly useful for -a planned (rolling) cluster restart where you can stop indexing and don't want to wait the default 5 minutes for -idle indices to be sync-flushed automatically. - -While handy, there are a couple of caveats for this API: - -1. Synced flush is a best effort operation. Any ongoing indexing operations will cause -the synced flush to fail on that shard. This means that some shards may be synced flushed while others aren't. See below for more. -2. The `sync_id` marker is removed as soon as the shard is flushed again. That is because a flush replaces the low level -lucene commit point where the marker is stored. Uncommitted operations in the transaction log do not remove the marker. -In practice, one should consider any indexing operation on an index as removing the marker as a flush can be triggered by Elasticsearch -at any time. - - -NOTE: It is harmless to request a synced flush while there is ongoing indexing. Shards that are idle will succeed and shards - that are not will fail. Any shards that succeeded will have faster recovery times. - - -[source,sh] --------------------------------------------------- -POST twitter/_flush/synced --------------------------------------------------- -// CONSOLE -// TEST[setup:twitter] - -The response contains details about how many shards were successfully sync-flushed and information about any failure. - -Here is what it looks like when all shards of a two shards and one replica index successfully -sync-flushed: - -[source,js] --------------------------------------------------- -{ - "_shards": { - "total": 2, - "successful": 2, - "failed": 0 - }, - "twitter": { - "total": 2, - "successful": 2, - "failed": 0 - } -} --------------------------------------------------- -// TESTRESPONSE[s/"successful": 2/"successful": 1/] - -Here is what it looks like when one shard group failed due to pending operations: - -[source,js] --------------------------------------------------- -{ - "_shards": { - "total": 4, - "successful": 2, - "failed": 2 - }, - "twitter": { - "total": 4, - "successful": 2, - "failed": 2, - "failures": [ - { - "shard": 1, - "reason": "[2] ongoing operations on primary" - } - ] - } -} --------------------------------------------------- -// NOTCONSOLE - -NOTE: The above error is shown when the synced flush fails due to concurrent indexing operations. The HTTP -status code in that case will be `409 CONFLICT`. - -Sometimes the failures are specific to a shard copy. The copies that failed will not be eligible for -fast recovery but those that succeeded still will be. This case is reported as follows: - -[source,js] --------------------------------------------------- -{ - "_shards": { - "total": 4, - "successful": 1, - "failed": 1 - }, - "twitter": { - "total": 4, - "successful": 3, - "failed": 1, - "failures": [ - { - "shard": 1, - "reason": "unexpected error", - "routing": { - "state": "STARTED", - "primary": false, - "node": "SZNr2J_ORxKTLUCydGX4zA", - "relocating_node": null, - "shard": 1, - "index": "twitter" - } - } - ] - } -} --------------------------------------------------- -// NOTCONSOLE - -NOTE: When a shard copy fails to sync-flush, the HTTP status code returned will be `409 CONFLICT`. - -The synced flush API can be applied to more than one index with a single call, -or even on `_all` the indices. - -[source,js] --------------------------------------------------- -POST kimchy,elasticsearch/_flush/synced +[[synced-flush-api]] +==== Synced Flush -POST _flush/synced --------------------------------------------------- -// CONSOLE +See <>. diff --git a/docs/reference/indices/synced-flush.asciidoc b/docs/reference/indices/synced-flush.asciidoc new file mode 100644 index 0000000000000..ba37ad33365fc --- /dev/null +++ b/docs/reference/indices/synced-flush.asciidoc @@ -0,0 +1,286 @@ +[[indices-synced-flush-api]] +=== Synced flush API +++++ +Synced flush +++++ + +Performs a synced flush on one or more indices. + +[source,js] +-------------------------------------------------- +POST /twitter/_flush/synced +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + + +[[synced-flush-api-request]] +==== {api-request-title} + +`POST //flush/synced` + +`GET //flush/synced` + +`POST /flush/synced` + +`GET /flush/synced` + + +[[synced-flush-api-desc]] +==== {api-description-title} + +[[synced-flush-using-api]] +===== Use the synced flush API + +Use the synced flush API to manually initiate a synced flush. +This can be useful for a planned cluster restart where +you can stop indexing but don't want to wait for 5 minutes until all indices +are marked as inactive and automatically sync-flushed. + +You can request a synced flush even if there is ongoing indexing activity, and +{es} will perform the synced flush on a "best-effort" basis: shards that do not +have any ongoing indexing activity will be successfully sync-flushed, and other +shards will fail to sync-flush. The successfully sync-flushed shards will have +faster recovery times as long as the `sync_id` marker is not removed by a +subsequent flush. + + +[[synced-flush-overview]] +===== Synced flush overview + +{es} keeps track of which shards have received indexing activity recently, and +considers shards that have not received any indexing operations for 5 minutes to +be inactive. + +When a shard becomes inactive {es} performs a special kind of flush +known as a *synced flush*. A synced flush performs a normal +<> on each replica of the shard, and then adds a marker known +as the `sync_id` to each replica to indicate that these copies have identical +Lucene indices. Comparing the `sync_id` markers of the two copies is a very +efficient way to check whether they have identical contents. + +When allocating shard replicas, {es} must ensure that each replica contains the +same data as the primary. If the shard copies have been synced-flushed and the +replica shares a `sync_id` with the primary then {es} knows that the two copies +have identical contents. This means there is no need to copy any segment files +from the primary to the replica, which saves a good deal of time during +recoveries and restarts. + +This is particularly useful for clusters having lots of indices which are very +rarely updated, such as with time-based indices. Without the synced flush +marker, recovery of this kind of cluster would be much slower. + + +[[synced-flush-sync-id-markers]] +===== Check for `sync_id` markers + +To check whether a shard has a `sync_id` marker or not, look for the `commit` +section of the shard stats returned by the <> API: + +[source,js] +-------------------------------------------------- +GET /twitter/_stats?filter_path=**.commit&level=shards <1> +-------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT twitter\nPOST twitter\/_flush\/synced\n/] + +<1> `filter_path` is used to reduce the verbosity of the response, but is entirely optional + +The API returns the following response: + +[source,js] +-------------------------------------------------- +{ + "indices": { + "twitter": { + "shards": { + "0": [ + { + "commit" : { + "id" : "3M3zkw2GHMo2Y4h4/KFKCg==", + "generation" : 3, + "user_data" : { + "translog_uuid" : "hnOG3xFcTDeoI_kvvvOdNA", + "history_uuid" : "XP7KDJGiS1a2fHYiFL5TXQ", + "local_checkpoint" : "-1", + "translog_generation" : "2", + "max_seq_no" : "-1", + "sync_id" : "AVvFY-071siAOuFGEO9P", <1> + "max_unsafe_auto_id_timestamp" : "-1", + "min_retained_seq_no" : "0" + }, + "num_docs" : 0 + } + } + ] + } + } + } +} +-------------------------------------------------- +// TESTRESPONSE[s/"id" : "3M3zkw2GHMo2Y4h4\/KFKCg=="/"id": $body.indices.twitter.shards.0.0.commit.id/] +// TESTRESPONSE[s/"translog_uuid" : "hnOG3xFcTDeoI_kvvvOdNA"/"translog_uuid": $body.indices.twitter.shards.0.0.commit.user_data.translog_uuid/] +// TESTRESPONSE[s/"history_uuid" : "XP7KDJGiS1a2fHYiFL5TXQ"/"history_uuid": $body.indices.twitter.shards.0.0.commit.user_data.history_uuid/] +// TESTRESPONSE[s/"sync_id" : "AVvFY-071siAOuFGEO9P"/"sync_id": $body.indices.twitter.shards.0.0.commit.user_data.sync_id/] +<1> the `sync id` marker + +NOTE: The `sync_id` marker is removed as soon as the shard is flushed again, and +{es} may trigger an automatic flush of a shard at any time if there are +unflushed operations in the shard's translog. In practice this means that one +should consider any indexing operation on an index as having removed its +`sync_id` markers. + + +[[synced-flush-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] ++ +To sync-flush all indices, +omit this parameter +or use a value of `_all` or `*`. + + +[[synced-flush-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 `open`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + + +[[synced-flush-api-response-codes]] +==== {api-response-codes-title} + +`200`:: +All shards successfully sync-flushed. + +`409`:: +A replica shard failed to sync-flush. + + +[[synced-flush-api-example]] +==== {api-examples-title} + + +[[synced-flush-api-specific-ex]] +===== Sync-flush a specific index + +[source,js] +---- +POST /kimchy/_flush +---- +// CONSOLE +// TEST[s/^/PUT kimchy\n/] + + +[[synced-flush-api-multi-ex]] +===== Synch-flush several indices + +[source,js] +-------------------------------------------------- +POST /kimchy,elasticsearch/_flush/synced +-------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT elasticsearch\n/] +// TEST[continued] + + +[[synced-flush-api-all-ex]] +===== Sync-flush all indices + +[source,js] +-------------------------------------------------- +POST /_flush/synced +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + +The response contains details about how many shards were successfully +sync-flushed and information about any failure. + +The following response indicates two shards +and one replica shard +successfully sync-flushed: + +[source,js] +-------------------------------------------------- +{ + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "twitter": { + "total": 2, + "successful": 2, + "failed": 0 + } +} +-------------------------------------------------- +// TESTRESPONSE[s/"successful": 2/"successful": 1/] + +The following response indicates one shard group failed +due to pending operations: + +[source,js] +-------------------------------------------------- +{ + "_shards": { + "total": 4, + "successful": 2, + "failed": 2 + }, + "twitter": { + "total": 4, + "successful": 2, + "failed": 2, + "failures": [ + { + "shard": 1, + "reason": "[2] ongoing operations on primary" + } + ] + } +} +-------------------------------------------------- +// NOTCONSOLE + +Sometimes the failures are specific to a shard replica. The copies that failed +will not be eligible for fast recovery but those that succeeded still will be. +This case is reported as follows: + +[source,js] +-------------------------------------------------- +{ + "_shards": { + "total": 4, + "successful": 1, + "failed": 1 + }, + "twitter": { + "total": 4, + "successful": 3, + "failed": 1, + "failures": [ + { + "shard": 1, + "reason": "unexpected error", + "routing": { + "state": "STARTED", + "primary": false, + "node": "SZNr2J_ORxKTLUCydGX4zA", + "relocating_node": null, + "shard": 1, + "index": "twitter" + } + } + ] + } +} +-------------------------------------------------- +// NOTCONSOLE diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.flush_synced.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.flush_synced.json index 1383224b92f81..3d7a8148b6877 100644 --- a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.flush_synced.json +++ b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.flush_synced.json @@ -1,6 +1,6 @@ { "indices.flush_synced": { - "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-flush.html#synced-flush-api", + "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-synced-flush-api.html", "stability": "stable", "methods": ["POST", "GET"], "url": {