Update index settings

PUT /{index}/_settings
PUT /_settings

Changes dynamic index settings in real time. For data streams, index setting changes are applied to all backing indices by default.

To revert a setting to the default value, use a null value. The list of per-index settings that can be updated dynamically on live indices can be found in index settings documentation. To preserve existing settings from being updated, set the preserve_existing parameter to true.

There are multiple valid ways to represent index settings in the request body. You can specify only the setting, for example:

		{
  "number_of_replicas": 1
}
		
	

Or you can use an index setting object:

		{
  "index": {
    "number_of_replicas": 1
  }
}
		
	

Or you can use dot annotation:

		{
  "index.number_of_replicas": 1
}
		
	

Or you can embed any of the aforementioned options in a settings object. For example:

		{
  "settings": {
    "index": {
      "number_of_replicas": 1
    }
  }
}
		
	

NOTE: You can only define new analyzers on closed indices. To add an analyzer, you must close the index, define the analyzer, and reopen the index. You cannot close the write index of a data stream. To update the analyzer for a data stream's write index and future backing indices, update the analyzer in the index template used by the stream. Then roll over the data stream to apply the new analyzer to the stream's write index and future backing indices. This affects searches and any new data added to the stream after the rollover. However, it does not affect the data stream's backing indices or their existing data. To change the analyzer for existing backing indices, you must create a new data stream and reindex your data into it.

Required authorization

Index privileges: manage

Read the reference documentation

Path Parameters

index union IndexName | [] IndexName optional

Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Leave it out to use /_settings.

Query Parameters

allow_no_indices boolean · default: false

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

expand_wildcards string ExpandWildcards · default: open

Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:

all: Match any data stream or index, including hidden ones.
open: Match open, non-hidden indices. Also matches any non-hidden data stream.
closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
none: Wildcard expressions are not accepted.

Values: all open closed hidden none

flat_settings boolean · default: false

If true, returns settings in flat format.

ignore_unavailable boolean · default: false

If true, returns settings in flat format.

master_timeout string Duration · default: 30s

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.

preserve_existing boolean · default: false

If true, existing index settings remain unchanged.

reopen boolean · default: false

Whether to close and reopen the index to apply non-dynamic settings. If set to true the indices to which the settings are being applied will be closed temporarily and then reopened in order to apply the changes.

timeout string Duration · default: 30s

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Request

Type: IndexSettings

Response

application/json

Examples

Request Console 1 / 8 languages

Console Kibana Dev Tools

PUT /my-index-000001/_settings
{
  "index" : {
    "number_of_replicas" : 2
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.putSettings({
  index: "my-index-000001",
  settings: {
    index: {
      number_of_replicas: 2,
    },
  },
});

Python Elasticsearch Python Client

resp = client.indices.put_settings(
    index="my-index-000001",
    settings={
        "index": {
            "number_of_replicas": 2
        }
    },
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/my-index-000001/_settings" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": {
      "number_of_replicas": 2
    }
  }'

Java Elasticsearch Java Client

client.indices().putSettings(p -> p
    .index("my-index-000001")
    .settings(s -> s
        .index(i -> i
            .numberOfReplicas("2")
        )
    )
);

C# Elasticsearch .NET Client

var response = await client.Indices
    .PutSettingsAsync(d1 => d1
        .Indices(new[] { "my-index-000001" })
        .Settings(d2 => d2
            .Index(d3 => d3
                .NumberOfReplicas(2)
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->putSettings([
    "index" => "my-index-000001",
    "body" => [
        "index" => [
            "number_of_replicas" => 2,
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.put_settings(
  index: "my-index-000001",
  body: {
    "index": {
      "number_of_replicas": 2
    }
  }
)

Response

No example

To revert a setting to the default value, use null.

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT /_settings
{
  "index" : {
    "refresh_interval" : null
  }
}

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_settings" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "index" : {
    "refresh_interval" : null
  }
}'

Response

No example

To add an analyzer, you must close the index (POST /my-index-000001/_close), define the analyzer, then reopen the index (POST /my-index-000001/_open).

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT /_settings
{
  "analysis": {
    "analyzer": {
      "content": {
        "type": "custom",
        "tokenizer": "whitespace"
      }
    }
  }
}

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_settings" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "analysis": {
    "analyzer": {
      "content": {
        "type": "custom",
        "tokenizer": "whitespace"
      }
    }
  }
}'

Response

No example

Required authorization

Path Parameters

Query Parameters { allow_no_indices , expand_wildcards , flat_settings , ignore_unavailable , master_timeout , preserve_existing , reopen , timeout , }

Request

Response

Query Parameters