Update index settings APIedit

Changes a dynamic index setting in real time.

For data streams, index setting changes are applied to all backing indices by default.

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

Requestedit

PUT /<target>/_settings

Path parametersedit

<target>

(Optional, string) Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported.

To target all data streams and indices in a cluster, omit this parameter or use _all or *.

Query parametersedit

allow_no_indices

(Optional, boolean) If true, the request does not return an error if a wildcard expression or _all value retrieves only missing or closed indices.

This parameter also applies to index aliases that point to a missing or closed index.

Defaults to false.

expand_wildcards

(Optional, string) Controls what kind of indices that wildcard expressions can expand to. Multiple values are accepted when separated by a comma, as in open,hidden. Valid values are:

all
Expand to open and closed indices, including hidden indices.
open
Expand only to open indices.
closed
Expand only to closed indices.
hidden
Expansion of wildcards will include hidden indices. Must be combined with open, closed, or both.
none
Wildcard expressions are not accepted.

Defaults to open.

flat_settings
(Optional, boolean) If true, returns settings in flat format. Defaults to false.
ignore_unavailable
(Optional, boolean) If true, missing or closed indices are not included in the response. Defaults to false.
preserve_existing
(Optional, boolean) If true, existing index settings remain unchanged. Defaults to false.
master_timeout
(Optional, time units) Specifies the period of time 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) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Request bodyedit

settings
(Optional, index setting object) Configuration options for the index. See Index Settings.

Examplesedit

Reset an index settingedit

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

PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : null
  }
}

The list of per-index settings which can be updated dynamically on live indices can be found in Index modules. To preserve existing settings from being updated, the preserve_existing request parameter can be set to true.

Bulk indexing usageedit

For example, the update settings API can be used to dynamically change the index from being more performant for bulk indexing, and then move it to more real time indexing state. Before the bulk indexing is started, use:

PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "-1"
  }
}

(Another optimization option is to start the index without any replicas, and only later adding them, but that really depends on the use case).

Then, once bulk indexing is done, the settings can be updated (back to the defaults for example):

PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "1s"
  }
}

And, a force merge should be called:

POST /my-index-000001/_forcemerge?max_num_segments=5

Update index analysisedit

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. See Use reindex to change mappings or settings.

For example, the following commands add the content analyzer to the my-index-000001 index:

POST /my-index-000001/_close

PUT /my-index-000001/_settings
{
  "analysis" : {
    "analyzer":{
      "content":{
        "type":"custom",
        "tokenizer":"whitespace"
      }
    }
  }
}

POST /my-index-000001/_open