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

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

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

[source,js]
--------------------------------------------------
PUT /twitter/_settings
{
    "index" : {
        "number_of_replicas" : 2
    }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]


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

`PUT /<index>/_settings`


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

include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
To update a setting for all indices,
use `_all` or exclude this parameter.


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

include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]

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

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

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

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

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


[[sample-api-query-params]]
==== {api-query-parms-title}

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

[[sample-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,js]
--------------------------------------------------
PUT /twitter/_settings
{
    "index" : {
        "refresh_interval" : null
    }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

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,js]
--------------------------------------------------
PUT /twitter/_settings
{
    "index" : {
        "refresh_interval" : "-1"
    }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

(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,js]
--------------------------------------------------
PUT /twitter/_settings
{
    "index" : {
        "refresh_interval" : "1s"
    }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

And, a force merge should be called:

[source,js]
--------------------------------------------------
POST /twitter/_forcemerge?max_num_segments=5
--------------------------------------------------
// CONSOLE
// 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.
For example,
the following commands add the `content` analyzer to `myindex`:

[source,js]
--------------------------------------------------
POST /twitter/_close

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

POST /twitter/_open
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]