Update the cluster settings | Elasticsearch API documentation (v8)

Update the cluster settings Generally available

PUT /_cluster/settings

Configure and update dynamic settings on a running cluster. You can also configure dynamic settings locally on an unstarted or shut down node in elasticsearch.yml.

Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a null value.

If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) elasticsearch.yml setting; 4) Default setting value. For example, you can apply a transient setting to override a persistent setting or elasticsearch.yml setting. However, a change to an elasticsearch.yml setting will not override a defined transient or persistent setting.

TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster. If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings. Only use elasticsearch.yml for static cluster settings and node settings. The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.

WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.

External documentation

Query parameters

flat_settings boolean

Return settings in flat format (default: false)
master_timeout string

Explicit operation timeout for connection to master node

Values are -1 or 0.
timeout string

Explicit operation timeout

Values are -1 or 0.

application/json

Body Required

persistent object

The settings that persist after the cluster restarts.
Hide persistent attribute Show persistent attribute object
- * object Additional properties
transient object

The settings that do not persist after the cluster restarts.
Hide transient attribute Show transient attribute object
- * object Additional properties

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- persistent object Required
  
  Hide persistent attribute Show persistent attribute object
  
  * object Additional properties
- transient object Required
  
  Hide transient attribute Show transient attribute object
  
  * object Additional properties

PUT /_cluster/settings

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

resp = client.cluster.put_settings(
    persistent={
        "indices.recovery.max_bytes_per_sec": "50mb"
    },
)

const response = await client.cluster.putSettings({
  persistent: {
    "indices.recovery.max_bytes_per_sec": "50mb",
  },
});

response = client.cluster.put_settings(
  body: {
    "persistent": {
      "indices.recovery.max_bytes_per_sec": "50mb"
    }
  }
)

$resp = $client->cluster()->putSettings([
    "body" => [
        "persistent" => [
            "indices.recovery.max_bytes_per_sec" => "50mb",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"persistent":{"indices.recovery.max_bytes_per_sec":"50mb"}}' "$ELASTICSEARCH_URL/_cluster/settings"

client.cluster().putSettings(p -> p
    .persistent("indices.recovery.max_bytes_per_sec", JsonData.fromJson("\"50mb\""))
);

Request examples

An example of a persistent update.

{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}

PUT `/_cluster/settings` to update the `action.auto_create_index` setting. The setting accepts a comma-separated list of patterns that you want to allow or you can prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. In this example, the auto-creation of indices called `my-index-000001` or `index10` is allowed, the creation of indices that match the pattern `index1*` is blocked, and the creation of any other indices that match the `ind*` pattern is allowed. Patterns are matched in the order specified.

{
  "persistent": {
    "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*" 
  }
}