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

[[indices-update-settings]]
=== Update index settings API
++++
<titleabbrev>Update index settings</titleabbrev>
++++

Changes a <<index-modules-settings,dynamic index setting>> in real time.

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

[source,console]
--------------------------------------------------
PUT /my-index-000001/_settings
{
  "index" : {
    "number_of_replicas" : 2
  }
}
--------------------------------------------------
// TEST[setup:my_index]


[[update-index-settings-api-request]]
==== {api-request-title}

`PUT /<target>/_settings`

[[update-index-settings-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-indices,index privilege>> for the target data stream, index,
or alias.

[[update-index-settings-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) 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`.

[[update-index-settings-api-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `false`.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=flat-settings]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

`preserve_existing`::
(Optional, Boolean) If `true`, existing index settings remain unchanged.
Defaults to `false`.

`reopen`::
(Optional, Boolean) If `true`, then any static settings that would ordinarily only
be updated on closed indices will be updated by automatically closing and reopening
the affected indices. If `false`, attempts to update static settings on open indices
will fail. Defaults to `false`.

NOTE: Changing index settings on an automatically closed index using the `reopen`
parameter will result in the index becoming unavailable momentarily while the index
is in the process of reopening.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]


[[update-index-settings-api-request-body]]
==== {api-request-body-title}

`settings`::
(Optional, <<index-modules-settings,index setting object>>) Configuration
options for the index. See <<index-modules-settings>>.

[[update-index-settings-api-example]]
==== {api-examples-title}

[[reset-index-setting]]
===== Reset an index setting
To revert a setting to the default value, use `null`. For example:

[source,console]
--------------------------------------------------
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : null
  }
}
--------------------------------------------------
// TEST[setup:my_index]

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]]
===== Bulk indexing usage

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:

[source,console]
--------------------------------------------------
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "-1"
  }
}
--------------------------------------------------
// TEST[setup:my_index]

(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):

[source,console]
--------------------------------------------------
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "1s"
  }
}
--------------------------------------------------
// TEST[continued]

And, a force merge should be called:

[source,console]
--------------------------------------------------
POST /my-index-000001/_forcemerge?max_num_segments=5
--------------------------------------------------
// TEST[continued]

[[update-settings-analysis]]
===== Update index analysis

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.

[NOTE]
====
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 <<create-index-template,index
template used by the stream>>. Then <<manually-roll-over-a-data-stream,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
<<data-streams-use-reindex-to-change-mappings-settings>>.
====

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

[source,console]
--------------------------------------------------
POST /my-index-000001/_close

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

POST /my-index-000001/_open
--------------------------------------------------
// TEST[setup:my_index]