Get index template APIedit

Returns information about one or more index templates.

GET /_index_template/template_1

Requestedit

GET /_index_template/<index-template>

Path parametersedit

<index-template>

(Required, string) Comma-separated list or wildcard expression of index template names used to limit the request.

To return all index templates, omit this parameter or use a value of *.

Query parametersedit

flat_settings
(Optional, boolean) If true, returns settings in flat format. Defaults to false.
local
(Optional, boolean) If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
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.

Examplesedit

Get index templates using a wildcard expressionedit

GET /_index_template/temp*

Get all index templatesedit

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.
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.
template
(Optional, object) This is the template to be applied, may optionally include a mappings, settings, or aliases configuration.
composed_of
(Optional, array of strings) An ordered list of component template names. Component templates will be merged in the order specified, meaning that the last component template specified has the highest precedence. See the component template reference for information.
priority
(Optional, integer) Priority to determine index template precedence when a new 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
(Optional, integer) Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch.
_meta
(Optional, object) Optional user metadata about the index template. May have any contents. This map is not automatically generated by Elasticsearch.

Examplesedit

Composing multiple component templatesedit

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.

For two component templates, the order they are specified changes the number of shards for an index:

PUT /_component_template/template_with_2_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/template_with_3_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 3
    }
  }
}

PUT /_index_template/template_1
{
  "index_patterns": ["t*"],
  "composed_of": ["template_with_2_shards", "template_with_3_shards"]
}

In this case, an index matching t* will have three primary shards. If the order of composed templates were reversed, the index would have two primary shards.

Simulating template compositionedit

Since templates can be composed not only of multiple component templates, but also the index template itself, there are two simulation APIs to determine what the resulting index settings will be.

To simulate the settings that would be applied to a matching index name:

POST /_index_template/_simulate_index/myindex

To simulate the settings that would be applied from a particular template:

POST /_index_template/_simulate/template_1

POST /_index_template/_simulate
{
  "index_patterns": ["foo"],
  "template": {
    "settings": {
      "number_of_replicas": 0
    }
  }
}

Here’s an example demonstrating simulating both an index name and template name:

PUT /_component_template/ct1 
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/ct2 
{
  "template": {
    "settings": {
      "index.number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT /_index_template/final-template 
{
  "index_patterns": ["logdata-*"],
  "composed_of": ["ct1", "ct2"],
  "priority": 5
}

POST /_index_template/_simulate_index/logdata-2019-02-01 

POST /_index_template/_simulate/final-template 

POST /_index_template/_simulate 
{
  "index_patterns": ["logdata-*"],
  "composed_of": ["ct2"],
  "priority": 10,
  "template": {
    "settings": {
      "index.number_of_replicas": 1
    }
  }
}

Creating a component template (ct1) setting the number of shards to two

Creating another component template (ct2) setting the number of replicas to zero with mappings

Creating an index template called "final" template using ct1 and ct2

Simulate the settings that would be applied for a new index "logdata-2019-02-01"

Simulate the settings composed using the "final-template" index template

Simulate the settings composed using a custom specified template

The output of the simulate API from the last example call looks like:

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_replicas" : "1" 
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : { 
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [ 
    {
      "name" : "final-template",
      "index_patterns" : [
        "logdata-*"
      ]
    }
  ]
}

The number of replicas from the simulated template body

The @timestamp field inherited from the "ct2" component template

Any overlapping templates that would have matched, but have lower priority

When simulating a template and specifying a template in the body of the request, the simulated template is not added to the existing templates, it is only used for the simulation.

Index template with index aliasesedit

You can include index aliases in an index template.

PUT _index_template/template_1
{
  "index_patterns" : ["te*"],
  "template": {
    "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

When an index is created that matches multiple index templates, only the index template with the highest priority is applied. For example:

PUT /_index_template/template_1
{
  "index_patterns" : ["t*"],
  "priority" : 0,
  "template": {
    "settings" : {
      "number_of_shards" : 1,
      "number_of_replicas": 0
    },
    "mappings" : {
      "_source" : { "enabled" : false }
    }
  }
}

PUT /_index_template/template_2
{
  "index_patterns" : ["te*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    },
    "mappings" : {
      "_source" : { "enabled" : true }
    }
  }
}

For indices that start with te*, _source will enabled, and the index will have two primary shards and one replica, because only template_2 will be applied.

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.

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 /_index_template/template_1
{
  "index_patterns" : ["foo", "bar"],
  "priority" : 0,
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

To check the version, you can use the get index template API.

Template metadataedit

You can use the _meta parameter to add optional metadata to an index template. This is a user-defined map that can contain any data. This data will be stored in the cluster state however, so keeping it short is preferrable.

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

To unset _meta, replace the template without specifying one.

PUT /_index_template/template_1
{
  "index_patterns": ["foo", "bar"],
  "template": {
    "settings" : {
        "number_of_shards" : 3
    }
  },
  "_meta": {
    "description": "set number of shards to three",
    "serialization": {
      "class": "MyIndexTemplate",
      "id": 17
    }
  }
}

To check the _meta, you can use the get index template API.

Data stream definitionedit

If a composable template should auto create a data stream instead of an index then a data_stream definition can be added to a composable template.

PUT /_index_template/template_1
{
  "index_patterns": ["logs-*"],
  "template": {
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  },
  "data_stream": {
    "timestamp_field": "@timestamp"
  }
}

Required properties of a data stream definition:

timestamp_field
(Required, string) The name of the timestamp field. This field must be present in all documents indexed into the data stream and must be of type date or date_nanos.