Update update-settings.asciidoc
[[cluster-update-settings]]
== Cluster Update Settings
-Allows to update cluster wide specific settings. Settings updated can
-either be persistent (applied across restarts) or transient (will not
-survive a full cluster restart). Here is an example:
+Use this API to review and change cluster-wide settings.
+
+To review cluster settings:
+
+[source,js]
+--------------------------------------------------
+GET /_cluster/settings
+--------------------------------------------------
+// CONSOLE
+
+Updates to settings can be persistent, meaning they apply across restarts, or transient, where they don't
+survive a full cluster restart. Here is an example of a persistent update:
[source,js]
--------------------------------------------------
@@ -16,7 +25,7 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE
-Or:
+This update is transient:
[source,js]
--------------------------------------------------
@@ -29,8 +38,7 @@ PUT /_cluster/settings?flat_settings=true
--------------------------------------------------
// CONSOLE
-The cluster responds with the settings updated. So the response for the
-last example will be:
+The response to an update returns the changed setting, as in this response to the transient example:
[source,js]
--------------------------------------------------
@@ -44,11 +52,14 @@ last example will be:
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]
-Resetting persistent or transient settings can be done by assigning a
-`null` value. If a transient setting is reset, the persistent setting
-is applied if available. Otherwise Elasticsearch will fallback to the setting
-defined at the configuration file or, if not existent, to the default
-value. Here is an example:
+You can reset persistent or transient settings by assigning a
+`null` value. If a transient setting is reset, the first one of these values that is defined is applied:
+
+* the persistent setting
+* the setting in the configuration file
+* the default value.
+
+This example resets a setting:
[source,js]
--------------------------------------------------
@@ -61,8 +72,7 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE
-Reset settings will not be included in the cluster response. So
-the response for the last example will be:
+The response does not include settings that have been reset:
[source,js]
--------------------------------------------------
@@ -74,8 +84,8 @@ the response for the last example will be:
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]
-Settings can also be reset using simple wildcards. For instance to reset
-all dynamic `indices.recovery` setting a prefix can be used:
+You can also reset settings using wildcards. For example, to reset
+all dynamic `indices.recovery` settings:
[source,js]
--------------------------------------------------
@@ -88,25 +98,19 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE
-Cluster wide settings can be returned using:
-
-[source,js]
---------------------------------------------------
-GET /_cluster/settings
---------------------------------------------------
-// CONSOLE
[float]
-=== Precedence of settings
+=== Order of Precedence
+
+The order of precedence for cluster settings is:
-Transient cluster settings take precedence over persistent cluster settings,
-which take precedence over settings configured in the `elasticsearch.yml`
-config file.
+1. transient cluster settings
+2. persistent cluster settings
+3. settings in the `elasticsearch.yml` configuration file.
-For this reason it is preferrable to use the `elasticsearch.yml` file only
-for local configurations, and set all cluster-wider settings with the
+It's best to use the `elasticsearch.yml` file only
+for local configurations, and set all cluster-wide settings with the
`settings` API.
-A list of dynamically updatable settings can be found in the
-<<modules,Modules>> documentation.
+You can find the list of settings that you can dynamically update in <<modules,Modules>>.
