Update index settings API
editUpdate index settings API
editChanges 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 } }
Request
editPUT /<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 targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
.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 tofalse
. -
ignore_unavailable
-
(Optional, Boolean) If
false
, the request returns an error if it targets a missing or closed index. Defaults tofalse
. -
preserve_existing
-
(Optional, Boolean) If
true
, existing index settings remain unchanged. Defaults tofalse
. -
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
editReset an index setting
editTo 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 usage
editFor 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 analysis
editYou 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?wait_for_active_shards=0 PUT /my-index-000001/_settings { "analysis" : { "analyzer":{ "content":{ "type":"custom", "tokenizer":"whitespace" } } } } POST /my-index-000001/_open