Cluster update settings APIedit

Updates cluster-wide settings.

Requestedit

PUT /_cluster/settings

Prerequisitesedit

  • If the Elasticsearch security features are enabled, you must have the manage cluster privilege to use this API.

Descriptionedit

With specifications in the request body, this API call can update cluster settings. Updates to settings can be persistent, meaning they apply across restarts, or transient, where they don’t survive a full cluster restart.

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.

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.

Transient settings are deprecated and will be removed in a future release. Prefer using persistent cluster settings instead.

Query parametersedit

flat_settings
(Optional, Boolean) If true, returns settings in flat format. Defaults to false.
include_defaults
(Optional, Boolean) If true, returns all default cluster settings. Defaults to false.
master_timeout
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
timeout
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Examplesedit

An example of a persistent update:

PUT /_cluster/settings
{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}

An example of a transient update:

PUT /_cluster/settings?flat_settings=true
{
  "transient" : {
    "indices.recovery.max_bytes_per_sec" : "20mb"
  }
}

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

{
  ...
  "persistent" : { },
  "transient" : {
    "indices.recovery.max_bytes_per_sec" : "20mb"
  }
}

This example resets a setting:

PUT /_cluster/settings
{
  "transient" : {
    "indices.recovery.max_bytes_per_sec" : null
  }
}

The response does not include settings that have been reset:

{
  ...
  "persistent" : {},
  "transient" : {}
}

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

PUT /_cluster/settings
{
  "transient" : {
    "indices.recovery.*" : null
  }
}