Create or update an index template

  • POST also PUT /_index_template/{name}
Auth

Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. Index templates are applied during data stream or index creation. For data streams, these settings and mappings are applied when the stream's backing indices are created. Settings and mappings specified in a create index API request override any settings or mappings specified in an index template. Changes to index templates do not affect existing indices, including the existing backing indices of a data stream.

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.

Multiple matching templates

If multiple index templates match the name of a new index or data stream, the template with the highest priority is used.

Multiple templates with overlapping index patterns at the same priority are not allowed and an error will be thrown when attempting to create a template matching an existing index template at identical priorities.

Composing aliases, mappings, and settings

When multiple component templates are specified in the composed_of field for an index template, they are merged in the order specified, meaning that later component templates override earlier component templates. Any mappings, settings, or aliases from the parent index template are merged in next. Finally, any configuration on the index request itself is merged. Mapping definitions are merged recursively, which means that later mapping components can introduce new field mappings and update the mapping configuration. If a field mapping is already contained in an earlier component, its definition will be completely overwritten by the later one. This recursive merging strategy applies not only to field mappings, but also root options like dynamic_templates and meta. If an earlier component contains a dynamic_templates block, then by default new dynamic_templates entries are appended onto the end. If an entry already exists with the same key, then it is overwritten by the new definition.

Required authorization

Cluster privileges manage_index_templates

Path parameters

name string required

Index or template name

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.

cause string · default: api

User defined reason for creating or updating the index template

Request body

index_patterns union oneOf

Array of wildcard (*) expressions used to match the names of data streams and indices during creation.

One of: string[] or string
composed_of string[]

An ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence.

template object

Template to be applied. It may optionally include an aliases, mappings, or settings configuration.

aliases map string to object

Aliases to add. If the index template includes a data_stream object, these are data stream aliases. Otherwise, these are index aliases. Data stream aliases ignore the index_routing, routing, and search_routing options.

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

mappings object

Mapping for fields in the index. If specified, this mapping can include field names, field data types, and mapping parameters.

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
enabled boolean
excludes string[]
includes string[]
mode enum

Supported values include:

  • disabled
  • stored
  • columnar_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 columnar_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
settings object

Configuration options for the index.

lifecycle object
data_retention string

If defined, every document added to this data stream will be stored at least for this time frame. Any time after this duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely.

effective_retention string

The least amount of time data should be kept by elasticsearch.

retention_determined_by enum

Configuration source that can influence the retention of a data stream.

Values: data_stream_configuration default_global_retention max_global_retention default_failures_retention
downsampling object[]

The list of downsampling rounds to execute as part of this downsampling configuration

after string required

The duration since rollover when this downsampling round should execute

fixed_interval string required

The downsample interval.

downsampling_method enum

The method used to downsample the data. There are two options aggregate and last_value. It requires downsampling to be defined. Defaults to aggregate.

Values: aggregate last_value
enabled boolean · default: true

If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

frozen_after string

The period after which data stream backing indices are automatically converted to partially mounted searchable snapshots. This field is valid only on main data stream lifecycles and cannot be set on failure-store lifecycles.

data_stream_options union oneOf nullable
One of:

Data stream options template contains the same information as DataStreamOptions but allows them to be set explicitly to null.

failure_store union oneOf nullable
One of:

Template equivalent of DataStreamFailureStore that allows nullable values.

enabled union boolean | string · default: true nullable

If defined, it turns the failure store on/off (true/false) for this data stream. A data stream failure store that's disabled (enabled: false) will redirect no new failed indices to the failure store; however, it will not remove any existing data from the failure store.

lifecycle union oneOf nullable

If defined, it specifies the lifecycle configuration for the failure store of this data stream.

One of:

Template equivalent of FailureStoreLifecycle that allows nullable values.

data_retention union string nullable

If defined, every document added to this data stream will be stored at least for this time frame. Any time after this duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely.

enabled boolean · default: true

If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

data_stream object

If this object is included, the template is used to create data streams and their backing indices. Supports an empty object. Data streams require a matching index template with a data_stream object.

hidden boolean
allow_custom_routing boolean
failure_store boolean
priority number

Priority to determine index template precedence when a new data stream or index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though it is of priority 0 (lowest priority). This number is not automatically generated by Elasticsearch.

version number

Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch. External systems can use these version numbers to simplify template management. To unset a version, replace the template without specifying one.

_meta object

Optional user metadata about the index template. It may have any contents. It is not automatically generated or used by Elasticsearch. This user-defined object is stored in the cluster state, so keeping it short is preferable To unset the metadata, replace the template without specifying it.

allow_auto_create boolean

This setting overrides the value of the action.auto_create_index cluster setting. If set to true in a template, then indices can be automatically created using that template even if auto-creation of indices is disabled via actions.auto_create_index. If set to false, then indices or data streams matching the template must always be explicitly created, and may never be automatically created.

ignore_missing_component_templates string[]

The configuration option ignore_missing_component_templates can be used when an index template references a component template that might not exist

deprecated boolean

Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.

Response

application/json
acknowledged boolean required

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