elasticsearch/docs/reference/cluster/update-settings.asciidoc

[[cluster-update-settings]]
== Cluster Update Settings

Use this API to review and change cluster-wide settings. 

To review cluster settings:

[source,js]
--------------------------------------------------
GET /_cluster/settings
--------------------------------------------------
// CONSOLE

By default, this API call only returns settings that have been explicitly defined, but can also <<cluster-get-settings,include the default settings>>.

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]
--------------------------------------------------
PUT /_cluster/settings
{
    "persistent" : {
        "indices.recovery.max_bytes_per_sec" : "50mb"
    }
}
--------------------------------------------------
// CONSOLE

This update is transient:

[source,js]
--------------------------------------------------
PUT /_cluster/settings?flat_settings=true
{
    "transient" : {
        "indices.recovery.max_bytes_per_sec" : "20mb"
    }
}
--------------------------------------------------
// CONSOLE

The response to an update returns the changed setting, as in this response to the transient example:

[source,js]
--------------------------------------------------
{
    ...
    "persistent" : { },
    "transient" : {
        "indices.recovery.max_bytes_per_sec" : "20mb"
    }
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]

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]
--------------------------------------------------
PUT /_cluster/settings
{
    "transient" : {
        "indices.recovery.max_bytes_per_sec" : null
    }
}
--------------------------------------------------
// CONSOLE

The response does not include settings that have been reset:

[source,js]
--------------------------------------------------
{
    ...
    "persistent" : {},
    "transient" : {}
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]

You can also reset settings using wildcards. For example, to reset
all dynamic `indices.recovery` settings:

[source,js]
--------------------------------------------------
PUT /_cluster/settings
{
    "transient" : {
        "indices.recovery.*" : null
    }
}
--------------------------------------------------
// CONSOLE


[float]
=== Order of Precedence

The order of precedence for cluster settings is:

1. transient cluster settings 
2. persistent cluster settings
3. settings in the `elasticsearch.yml` configuration file.

It's best to set all cluster-wide settings with the `settings` API and use the
`elasticsearch.yml` file only for local configurations. This way you can be sure that
the setting is the same on all nodes. If, on the other hand, you define different
settings on different nodes by accident using the configuration file, it is very
difficult to notice these discrepancies.

You can find the list of settings that you can dynamically update in <<modules,Modules>>.