Create or update an index template

PUT /_template/{name}

Index templates define settings, mappings, and aliases that can be applied automatically to new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.

IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

Composable templates always take precedence over legacy templates. If no composable template matches a new index, matching legacy templates are applied according to their order.

Index templates are only applied during index creation. Changes to index templates do not affect existing indices. Settings and mappings specified in create index API requests override any settings or mappings specified in an index template.

You can use C-style /* *\/ block comments in index templates. You can include comments anywhere in the request body, except before the opening curly bracket.

Indices matching multiple templates

Multiple index templates can potentially match an index, in this case, both the settings and mappings are merged into the final configuration of the index. The order of the merging can be controlled using the order parameter, with lower order being applied first, and higher orders overriding them. NOTE: Multiple matching templates with the same order value will result in a non-deterministic merging order.

External documentation

Path parameters

  • namestring Required

    The name of the template

Query parameters

  • createboolean

    If true, this request cannot replace or update existing index templates.

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

  • ordernumber

    Order in which Elasticsearch applies this template if index matches multiple templates.

    Templates with lower 'order' values are merged first. Templates with higher 'order' values are merged later, overriding templates with lower values.

  • causestring

    User defined reason for creating/updating the index template

application/json

BodyRequired

  • aliasesobject

    Aliases for the index.

    Hide aliases attribute Show aliases attribute object
  • index_patternsstring | array[string]

    Array of wildcard expressions used to match the names of indices during creation.

  • mappingsobject
    Hide mappings attributes Show mappings attributes object
    • all_fieldobject
      Hide all_field attributes Show all_field attributes object
    • dynamicstring

      Values are strict, runtime, true, or false.

    • dynamic_templatesarray[object]
    • Hide _field_names attribute Show _field_names attribute object
    • Hide index_field attribute Show index_field attribute object
    • _metaobject
      Hide _meta attribute Show _meta attribute object
      • *object Additional properties
    • _routingobject
      Hide _routing attribute Show _routing attribute object
    • _sizeobject
      Hide _size attribute Show _size attribute object
    • _sourceobject
      Hide _source attributes Show _source attributes object
    • runtimeobject
      Hide runtime attribute Show runtime attribute object
      • *object Additional properties
        Hide * attributes Show * attributes object
        • fieldsobject

          For type composite

          Hide fields attribute Show fields attribute object
          • *object Additional properties
            Hide * attribute Show * attribute object
            • typestring Required

              Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

        • fetch_fieldsarray[object]

          For type lookup

          Hide fetch_fields attributes Show fetch_fields attributes object
          • fieldstring Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • formatstring
        • formatstring

          A custom format for date type runtime fields.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • scriptobject
          Hide script attributes Show script attributes object
          • sourcestring | object

            One of:
          • idstring
          • paramsobject

            Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

            Hide params attribute Show params attribute object
            • *object Additional properties
          • langstring

            Any of:

            Values are painless, expression, mustache, or java.

          • optionsobject
            Hide options attribute Show options attribute object
            • *string Additional properties
        • typestring Required

          Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

    • enabledboolean
    • Values are true or false.

    • Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  • ordernumber

    Order in which Elasticsearch applies this template if index matches multiple templates.

    Templates with lower 'order' values are merged first. Templates with higher 'order' values are merged later, overriding templates with lower values.

  • settingsobject
    Hide settings attributes Show settings attributes object
    • indexobject
    • modestring
    • Hide soft_deletes attributes Show soft_deletes attributes object
      • enabledboolean

        Indicates whether soft deletes are enabled on the index.

      • Hide retention_lease attribute Show retention_lease attribute object
        • periodstring 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.

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

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

    • auto_expand_replicasstring | null

      One of:

      A null value that is to be interpreted as an actual value, unless other uses of null that are equivalent to a missing value. It is used for exemple in settings, where using the NullValue for a setting will reset it to its default value.

    • mergeobject
      Hide merge attribute Show merge attribute object
      • schedulerobject
        Hide scheduler attributes Show scheduler attributes object
        • max_thread_countnumber | 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.

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

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

    • blocksobject
      Hide blocks attributes Show blocks attributes object
      • read_onlyboolean | 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.

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

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

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

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

    • analyzeobject
      Hide analyze attribute Show analyze attribute object
      • max_token_countnumber | 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.

    • highlightobject
      Hide highlight attribute Show highlight attribute object
    • routingobject
      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.

    • lifecycleobject
      Hide lifecycle attributes Show lifecycle attributes object
      • namestring
      • indexing_completeboolean | 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.

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

      • prefer_ilmboolean | string

        Preference for the system that manages a data stream backing index (preferring ILM when both ILM and DLM are applicable for an index).

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

      One of:

      Time unit for milliseconds

    • uuidstring
    • versionobject
      Hide version attributes Show version attributes object
    • translogobject
      Hide translog attributes Show translog 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.

      • Values are request, REQUEST, async, or ASYNC.

      • retentionobject
        Hide retention attributes Show retention attributes object
        • agestring

          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.

    • Hide query_string attribute Show query_string attribute object
      • lenientboolean | string Required

        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.

    • analysisobject
      Hide analysis attributes Show analysis attributes object
    • settingsobject
    • Hide time_series attributes Show time_series attributes object
      • end_timestring | 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.

        One of:

        Time unit for milliseconds

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

        One of:

        Time unit for milliseconds

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

    • mappingobject
      Hide mapping attributes Show mapping attributes object
      • coerceboolean
      • Hide total_fields attributes Show total_fields attributes object
        • limitnumber | 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_limitboolean | 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.

      • depthobject
        Hide depth attribute Show depth attribute object
        • limitnumber

          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.

      • Hide nested_fields attribute Show nested_fields attribute object
        • limitnumber

          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.

      • Hide nested_objects attribute Show nested_objects attribute object
        • limitnumber

          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.

      • Hide field_name_length attribute Show field_name_length attribute object
        • limitnumber

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

      • Hide dimension_fields attribute Show dimension_fields attribute object
        • limitnumber

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

      • sourceobject
        Hide source attribute Show source attribute object
        • modestring Required

          Values are disabled, stored, or synthetic.

    • Hide indexing.slowlog attributes Show indexing.slowlog attributes object
      • levelstring
      • sourcenumber
      • reformatboolean
      • thresholdobject
        Hide threshold attribute Show threshold attribute object
        • indexobject
          Hide index attributes Show index attributes object
          • warnstring

            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.

          • infostring

            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.

          • debugstring

            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.

          • tracestring

            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.

    • Hide indexing_pressure attribute Show indexing_pressure attribute object
      • memoryobject Required
        Hide memory attribute Show memory attribute object
        • limitnumber

          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.

    • storeobject
      Hide store attributes Show store attributes object
      • typestring Required

        Any of:

        Values are fs, niofs, mmapfs, or hybridfs.

      • allow_mmapboolean

        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.

  • versionnumber

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledgedboolean Required

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

PUT /_template/{name}
curl \
 --request PUT 'http://api.example.com/_template/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"index_patterns\": [\n    \"te*\",\n    \"bar*\"\n  ],\n  \"settings\": {\n    \"number_of_shards\": 1\n  },\n  \"mappings\": {\n    \"_source\": {\n      \"enabled\": false\n    }\n  },\n  \"properties\": {\n    \"host_name\": {\n      \"type\": \"keyword\"\n    },\n    \"created_at\": {\n      \"type\": \"date\",\n      \"format\": \"EEE MMM dd HH:mm:ss Z yyyy\"\n    }\n  }\n}"'
{
  "index_patterns": [
    "te*",
    "bar*"
  ],
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    }
  },
  "properties": {
    "host_name": {
      "type": "keyword"
    },
    "created_at": {
      "type": "date",
      "format": "EEE MMM dd HH:mm:ss Z yyyy"
    }
  }
}
You can include index aliases in an index template. During index creation, the `{index}` placeholder in the alias name will be replaced with the actual index name that the template gets applied to.
{
  "index_patterns": [
    "te*"
  ],
  "settings": {
    "number_of_shards": 1
  },
  "aliases": {
    "alias1": {},
    "alias2": {
      "filter": {
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    },
    "{index}-alias": {}
  }
}