Create or update a legacy index template

  • POST also PUT /_template/{name}
Auth Deprecated

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.

Read the reference documentation

Required authorization

Cluster privileges manage_index_templates manage

Path parameters

name string required

The name of the template

Query parameters

create boolean · default: false

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

master_timeout string · default: 30s

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.

order number

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.

cause string

User defined reason for creating or updating the index template

Request body

aliases map string to object

Aliases for the index.

<string> object
filter {} Query

Query used to limit documents the alias can access.

index_routing string

Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.

is_hidden boolean · default: false

If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

is_write_index boolean · default: false

If true, the index is the write index for the alias.

routing string

Value used to route indexing and search operations to a specific shard.

search_routing string

Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.

index_patterns union string | string[]

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

mappings object

Mapping for fields in the index.

all_field object
analyzer string required
enabled boolean required
omit_norms boolean required
search_analyzer string required
similarity string required
store boolean required
store_term_vector_offsets boolean required
store_term_vector_payloads boolean required
store_term_vector_positions boolean required
store_term_vectors boolean required
date_detection boolean
dynamic enum
Values: strict runtime true false
dynamic_date_formats string[]
dynamic_templates string to object[]
_field_names object
enabled boolean required
index_field object
enabled boolean required
_meta object
numeric_detection boolean
properties map string to oneOf
_routing object
required boolean required
_size object
enabled boolean required
_source object
compress boolean
compress_threshold string
enabled boolean
excludes string[]
includes string[]
mode enum

Supported values include:

  • disabled
  • stored
  • synthetic: Instead of storing source documents on disk exactly as you send them, Elasticsearch can reconstruct source content on the fly upon retrieval.
Values: disabled stored synthetic
runtime map string to object
<string> object
fields map string to object

For type composite

<string> object
type enum required
Values: boolean composite date double geo_point geo_shape ip keyword long lookup
fetch_fields object[]

For type lookup

field string required
format string
format string

A custom format for date type runtime fields.

input_field string

For type lookup

target_field string

For type lookup

target_index string

For type lookup

script string

Painless script executed at query time.

on_script_error enum
Values: fail continue
type enum required

Field type, which can be: boolean, composite, date, double, geo_point, ip,keyword, long, or lookup.

Values: boolean composite date double geo_point geo_shape ip keyword long lookup
enabled boolean
subobjects enum
Values: true false
_data_stream_timestamp object
enabled boolean required
order number

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.

settings object

Configuration options for the index.

version number

Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch. To unset a version, replace the template without specifying one.

Response

application/json
acknowledged boolean required

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