187 lines
4.9 KiB
Plaintext
187 lines
4.9 KiB
Plaintext
[[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-path-params]]
|
||
==== {api-path-parms-title}
|
||
|
||
`<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 `*`.
|
||
|
||
|
||
[[update-index-settings-api-query-params]]
|
||
==== {api-query-parms-title}
|
||
|
||
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
||
+
|
||
Defaults to `false`.
|
||
|
||
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
||
+
|
||
Defaults to `open`.
|
||
|
||
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings]
|
||
|
||
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
||
|
||
`preserve_existing`::
|
||
(Optional, boolean) If `true`, existing index settings remain unchanged.
|
||
Defaults to `false`.
|
||
|
||
include::{es-repo-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-a-data-stream-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]
|