Docs
You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.
Elasticsearch Reference [7.x] » REST APIs » Index APIs » Put index template API
« Open index API Put mapping API »

Put index template APIedit

Creates or updates an index template.

PUT _template/template_1
{
  "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"
      }
    }
  }
}

Requestedit

PUT /_template/<index-template>

Descriptionedit

Use the PUT index template API to create or update an index template.

Index templates define settings and mappings that you can automatically apply when creating new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.

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.

Comments in index templatesedit

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.

Getting templatesedit

See Get index template.

Path parametersedit

<index-template>
(Required, string) Name of the index template to create.

Query parametersedit

create
(Optional, boolean) If true, this request cannot replace or update existing index templates. Defaults to false.
flat_settings
(Optional, boolean) If true, returns settings in flat format. Defaults to false.
include_type_name
[7.0.0] Deprecated in 7.0.0. Mapping types have been deprecated. See Removal of mapping types. (Optional, boolean) If true, a mapping type is expected in the body of mappings. Defaults to false.
order

(Optional,integer) 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.

timeout
(Optional, time units) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
master_timeout
(Optional, time units) Specifies the period of time 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. Defaults to 30s.

Request bodyedit

index_patterns
(Required, array of strings) Array of wildcard expressions used to match the names of indices during creation.
aliases
(Optional, alias object) Index aliases which include the index. See Update index alias.
mappings

(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:

See Mapping.

settings
(Optional, index setting object) Configuration options for the index. See Index Settings.
version
(Optional, integer) Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch.

Examplesedit

Index template with index aliasesedit

You can include index aliases in an index template.

PUT _template/template_1
{
    "index_patterns" : ["te*"],
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user" : "kimchy" }
            },
            "routing" : "kimchy"
        },
        "{index}-alias" : {} 
    }
}

the {index} placeholder in the alias name will be replaced with the actual index name that the template gets applied to, during index creation.

Indices matching multiple templatesedit

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. For example:

PUT /_template/template_1
{
    "index_patterns" : ["*"],
    "order" : 0,
    "settings" : {
        "number_of_shards" : 1
    },
    "mappings" : {
        "_source" : { "enabled" : false }
    }
}

PUT /_template/template_2
{
    "index_patterns" : ["te*"],
    "order" : 1,
    "settings" : {
        "number_of_shards" : 1
    },
    "mappings" : {
        "_source" : { "enabled" : true }
    }
}

The above will disable storing the _source, but for indices that start with te*, _source will still be enabled. Note, for mappings, the merging is "deep", meaning that specific object/property based mappings can easily be added/overridden on higher order templates, with lower order templates providing the basis.

Multiple matching templates with the same order value will result in a non-deterministic merging order.

Template versioningedit

You can use the version parameter to add an optional version number to an index template. External systems can use these version numbers to simplify template management.

The version parameter is completely optional and not automatically generated by Elasticsearch.

To unset a version, replace the template without specifying one.

PUT /_template/template_1
{
    "index_patterns" : ["*"],
    "order" : 0,
    "settings" : {
        "number_of_shards" : 1
    },
    "version": 123
}

To check the version, you can use the get index template API with the filter_path query parameter to return only the version number:

GET /_template/template_1?filter_path=*.version

The API returns the following response:

{
  "template_1" : {
    "version" : 123
  }
}
« Open index API Put mapping API »