IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Unfreeze index API Update mapping API »
Elastic Docs ›Elasticsearch Guide [8.9] ›REST APIs ›Index APIs

Update index settings API

edit

Update index settings API

edit

Changes a dynamic index setting in real time.

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

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

Request

edit

PUT /<target>/_settings

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the manage index privilege for the target data stream, index, or alias.

Path parameters

edit
<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.

Query parameters

edit
allow_no_indices

(Optional, Boolean) 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.

Defaults to false.

expand_wildcards

(Optional, string) 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. Valid values are:

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 patterns 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 false, the request returns an error if it targets a missing or closed index. Defaults to false.
preserve_existing
(Optional, Boolean) If true, existing index settings remain unchanged. Defaults to false.
master_timeout
(Optional, time units) 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. Defaults to 30s.
timeout
(Optional, time units) Period 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 body

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

Examples

edit

Reset an index setting

edit

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

response = client.indices.put_settings(
  index: 'my-index-000001',
  body: {
    index: {
      refresh_interval: nil
    }
  }
)
puts response
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 usage

edit

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:

response = client.indices.put_settings(
  index: 'my-index-000001',
  body: {
    index: {
      refresh_interval: '-1'
    }
  }
)
puts response
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):

response = client.indices.put_settings(
  index: 'my-index-000001',
  body: {
    index: {
      refresh_interval: '1s'
    }
  }
)
puts response
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "1s"
  }
}

And, a force merge should be called:

response = client.indices.forcemerge(
  index: 'my-index-000001',
  max_num_segments: 5
)
puts response
POST /my-index-000001/_forcemerge?max_num_segments=5

Update index analysis

edit

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:

response = client.indices.close(
  index: 'my-index-000001'
)
puts response

response = client.indices.put_settings(
  index: 'my-index-000001',
  body: {
    analysis: {
      analyzer: {
        content: {
          type: 'custom',
          tokenizer: 'whitespace'
        }
      }
    }
  }
)
puts response

response = client.indices.open(
  index: 'my-index-000001'
)
puts response
POST /my-index-000001/_close

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

POST /my-index-000001/_open
« Unfreeze index API Update mapping API »