Update index settings

PUT /_settings

Changes dynamic index settings in real time. For data streams, index setting changes are applied to all backing indices by default.

Query parameters

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

  • expand_wildcards string | array[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.

  • If true, returns settings in flat format.

  • If true, returns settings in flat format.

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

  • If true, existing index settings remain unchanged.

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

application/json

Body Required

  • index object

    Additional properties are allowed.

  • mode string
  • Additional properties are allowed.

    Hide soft_deletes attributes Show soft_deletes attributes object
    • enabled boolean

      Indicates whether soft deletes are enabled on the index.

    • Additional properties are allowed.

      Hide retention_lease attribute Show retention_lease attribute object
      • period string Required

        A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • sort object

    Additional properties are allowed.

    Hide sort attributes Show sort attributes object
  • Values are true, false, or checksum.

  • codec string
  • routing_partition_size number | string

    Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

    Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

  • merge object

    Additional properties are allowed.

    Hide merge attribute Show merge attribute object
  • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • blocks object

    Additional properties are allowed.

    Hide blocks attributes Show blocks attributes object
  • analyze object

    Additional properties are allowed.

    Hide analyze attribute Show analyze attribute object
  • Additional properties are allowed.

    Hide highlight attribute Show highlight attribute object
  • routing object

    Additional properties are allowed.

    Hide routing attributes Show routing attributes object
  • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • Additional properties are allowed.

    Hide lifecycle attributes Show lifecycle attributes object
    • name string
    • indexing_complete boolean | string

      Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

      Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

    • If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds.

    • Set to true to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern .*-{date_format}-\d+, where the date_format is yyyy.MM.dd and the trailing digits are optional. An index that was rolled over would normally match the full format, for example logs-2016.10.31-000002). If the index name doesn’t match the pattern, index creation fails.

    • step object

      Additional properties are allowed.

      Hide step attribute Show step attribute object
      • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see Rollover.

  • creation_date number | string

    Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

    Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

  • creation_date_string string | number

    A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

  • uuid string
  • version object

    Additional properties are allowed.

    Hide version attributes Show version attributes object
  • translog object

    Additional properties are allowed.

    Hide translog attributes Show translog attributes object
  • Additional properties are allowed.

    Hide query_string attribute Show query_string attribute object
  • analysis object

    Additional properties are allowed.

    Hide analysis attributes Show analysis attributes object
  • settings object

    Additional properties are allowed.

  • Additional properties are allowed.

    Hide time_series attributes Show time_series attributes object
  • queries object

    Additional properties are allowed.

    Hide queries attribute Show queries attribute object
    • cache object

      Additional properties are allowed.

      Hide cache attribute Show cache attribute object
  • Configure custom similarity settings to customize how search results are scored.

  • mapping object

    Additional properties are allowed.

    Hide mapping attributes Show mapping attributes object
    • coerce boolean
    • Additional properties are allowed.

      Hide total_fields attributes Show total_fields attributes object
      • limit number | string

        The maximum number of fields in an index. Field and object mappings, as well as field aliases count towards this limit. The limit is in place to prevent mappings and searches from becoming too large. Higher values can lead to performance degradations and memory issues, especially in clusters with a high load or few resources.

      • ignore_dynamic_beyond_limit boolean | string

        This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Limit of total fields [X] has been exceeded. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field.

    • depth object

      Additional properties are allowed.

      Hide depth attribute Show depth attribute object
      • limit number

        The maximum depth for a field, which is measured as the number of inner objects. For instance, if all fields are defined at the root object level, then the depth is 1. If there is one object mapping, then the depth is 2, etc.

    • Additional properties are allowed.

      Hide nested_fields attribute Show nested_fields attribute object
      • limit number

        The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index.

    • Additional properties are allowed.

      Hide nested_objects attribute Show nested_objects attribute object
      • limit number

        The maximum number of nested JSON objects that a single document can contain across all nested types. This limit helps to prevent out of memory errors when a document contains too many nested objects.

    • Additional properties are allowed.

      Hide field_name_length attribute Show field_name_length attribute object
      • limit number

        Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is Long.MAX_VALUE (no limit).

    • Additional properties are allowed.

      Hide dimension_fields attribute Show dimension_fields attribute object
      • limit number

        [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

  • Additional properties are allowed.

    Hide indexing.slowlog attributes Show indexing.slowlog attributes object
    • level string
    • source number
    • reformat boolean
    • Additional properties are allowed.

      Hide threshold attribute Show threshold attribute object
      • index object

        Additional properties are allowed.

        Hide index attributes Show index attributes object
        • warn string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • info string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • debug string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • trace string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • Additional properties are allowed.

    Hide indexing_pressure attribute Show indexing_pressure attribute object
    • memory object Required

      Additional properties are allowed.

      Hide memory attribute Show memory attribute object
      • limit number

        Number of outstanding bytes that may be consumed by indexing requests. When this limit is reached or exceeded, the node will reject new coordinating and primary operations. When replica operations consume 1.5x this limit, the node will reject new replica operations. Defaults to 10% of the heap.

  • store object

    Additional properties are allowed.

    Hide store attributes Show store attributes object
    • type string Required

    • allow_mmap boolean

      You can restrict the use of the mmapfs and the related hybridfs store type via the setting node.store.allow_mmap. This is a boolean setting indicating whether or not memory-mapping is allowed. The default is to allow it. This setting is useful, for example, if you are in an environment where you can not control the ability to create a lot of memory maps so you need disable the ability to use memory-mapping.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_settings
curl \
 -X PUT http://api.example.com/_settings \
 -H "Content-Type: application/json" \
 -d '{"index":{},"mode":"string","routing_path":"string","soft_deletes":{"enabled":true,"retention_lease":{"period":"string"}},"sort":{"field":"string","order":"asc","mode":"min","missing":"_last"},"number_of_shards":42.0,"number_of_replicas":42.0,"number_of_routing_shards":42.0,"check_on_startup":"true","codec":"string","":"string","load_fixed_bitset_filters_eagerly":true,"hidden":true,"auto_expand_replicas":"string","merge":{"scheduler":{"":42.0}},"search":{"idle":{"after":"string"},"slowlog":{"level":"string","source":42.0,"reformat":true,"threshold":{"query":{"warn":"string","info":"string","debug":"string","trace":"string"},"fetch":{"warn":"string","info":"string","debug":"string","trace":"string"}}}},"refresh_interval":"string","max_result_window":42.0,"max_inner_result_window":42.0,"max_rescore_window":42.0,"max_docvalue_fields_search":42.0,"max_script_fields":42.0,"max_ngram_diff":42.0,"max_shingle_diff":42.0,"blocks":{"":true},"max_refresh_listeners":42.0,"analyze":{"":42.0},"highlight":{"max_analyzed_offset":42.0},"max_terms_count":42.0,"max_regex_length":42.0,"routing":{"allocation":{"enable":"all","include":{"_tier_preference":"string","_id":"string"},"initial_recovery":{"_id":"string"},"disk":{"threshold_enabled":true}},"rebalance":{"enable":"all"}},"gc_deletes":"string","default_pipeline":"string","final_pipeline":"string","lifecycle":{"name":"string","":true,"origination_date":42.0,"parse_origination_date":true,"step":{"wait_time_threshold":"string"},"rollover_alias":"string"},"provided_name":"string","uuid":"string","version":{"created":"string","created_string":"string"},"verified_before_close":true,"format":"string","max_slices_per_scroll":42.0,"translog":{"sync_interval":"string","durability":"request","":42.0,"retention":{"":42.0,"age":"string"}},"query_string":{"":true},"priority":42.0,"top_metrics_max_size":42.0,"analysis":{"analyzer":{},"char_filter":{},"filter":{},"normalizer":{},"tokenizer":{}},"settings":{},"time_series":{"":"string"},"queries":{"cache":{"enabled":true}},"similarity":{},"mapping":{"coerce":true,"total_fields":{"limit":42.0,"ignore_dynamic_beyond_limit":true},"depth":{"limit":42.0},"nested_fields":{"limit":42.0},"nested_objects":{"limit":42.0},"field_name_length":{"limit":42.0},"dimension_fields":{"limit":42.0},"ignore_malformed":true},"indexing.slowlog":{"level":"string","source":42.0,"reformat":true,"threshold":{"index":{"warn":"string","info":"string","debug":"string","trace":"string"}}},"indexing_pressure":{"memory":{"limit":42.0}},"store":{"":"fs","allow_mmap":true}}'
Request examples
{
  "index": {},
  "mode": "string",
  "routing_path": "string",
  "soft_deletes": {
    "enabled": true,
    "retention_lease": {
      "period": "string"
    }
  },
  "sort": {
    "field": "string",
    "order": "asc",
    "mode": "min",
    "missing": "_last"
  },
  "number_of_shards": 42.0,
  "number_of_replicas": 42.0,
  "number_of_routing_shards": 42.0,
  "check_on_startup": "true",
  "codec": "string",
  "": "string",
  "load_fixed_bitset_filters_eagerly": true,
  "hidden": true,
  "auto_expand_replicas": "string",
  "merge": {
    "scheduler": {
      "": 42.0
    }
  },
  "search": {
    "idle": {
      "after": "string"
    },
    "slowlog": {
      "level": "string",
      "source": 42.0,
      "reformat": true,
      "threshold": {
        "query": {
          "warn": "string",
          "info": "string",
          "debug": "string",
          "trace": "string"
        },
        "fetch": {
          "warn": "string",
          "info": "string",
          "debug": "string",
          "trace": "string"
        }
      }
    }
  },
  "refresh_interval": "string",
  "max_result_window": 42.0,
  "max_inner_result_window": 42.0,
  "max_rescore_window": 42.0,
  "max_docvalue_fields_search": 42.0,
  "max_script_fields": 42.0,
  "max_ngram_diff": 42.0,
  "max_shingle_diff": 42.0,
  "blocks": {
    "": true
  },
  "max_refresh_listeners": 42.0,
  "analyze": {
    "": 42.0
  },
  "highlight": {
    "max_analyzed_offset": 42.0
  },
  "max_terms_count": 42.0,
  "max_regex_length": 42.0,
  "routing": {
    "allocation": {
      "enable": "all",
      "include": {
        "_tier_preference": "string",
        "_id": "string"
      },
      "initial_recovery": {
        "_id": "string"
      },
      "disk": {
        "threshold_enabled": true
      }
    },
    "rebalance": {
      "enable": "all"
    }
  },
  "gc_deletes": "string",
  "default_pipeline": "string",
  "final_pipeline": "string",
  "lifecycle": {
    "name": "string",
    "": true,
    "origination_date": 42.0,
    "parse_origination_date": true,
    "step": {
      "wait_time_threshold": "string"
    },
    "rollover_alias": "string"
  },
  "provided_name": "string",
  "uuid": "string",
  "version": {
    "created": "string",
    "created_string": "string"
  },
  "verified_before_close": true,
  "format": "string",
  "max_slices_per_scroll": 42.0,
  "translog": {
    "sync_interval": "string",
    "durability": "request",
    "": 42.0,
    "retention": {
      "": 42.0,
      "age": "string"
    }
  },
  "query_string": {
    "": true
  },
  "priority": 42.0,
  "top_metrics_max_size": 42.0,
  "analysis": {
    "analyzer": {},
    "char_filter": {},
    "filter": {},
    "normalizer": {},
    "tokenizer": {}
  },
  "settings": {},
  "time_series": {
    "": "string"
  },
  "queries": {
    "cache": {
      "enabled": true
    }
  },
  "similarity": {},
  "mapping": {
    "coerce": true,
    "total_fields": {
      "limit": 42.0,
      "ignore_dynamic_beyond_limit": true
    },
    "depth": {
      "limit": 42.0
    },
    "nested_fields": {
      "limit": 42.0
    },
    "nested_objects": {
      "limit": 42.0
    },
    "field_name_length": {
      "limit": 42.0
    },
    "dimension_fields": {
      "limit": 42.0
    },
    "ignore_malformed": true
  },
  "indexing.slowlog": {
    "level": "string",
    "source": 42.0,
    "reformat": true,
    "threshold": {
      "index": {
        "warn": "string",
        "info": "string",
        "debug": "string",
        "trace": "string"
      }
    }
  },
  "indexing_pressure": {
    "memory": {
      "limit": 42.0
    }
  },
  "store": {
    "": "fs",
    "allow_mmap": true
  }
}
Response examples (200)
{
  "acknowledged": true
}