Create Or Update Index Template API

Introduced 1.0

Use the Create or Update Index Template API to create indexes with predefined mappings and settings as well as update existing index templates.

Endpoints

PUT _index_template/{template-name}
POST _index_template/{template-name}

Path parameters

Query parameters

The following optional query parameters are supported.

Request body fields

The following options can be used in the request body to customize the index template.

Template

You can use the following objects with the template option in the request body.

aliases

The name of the alias to associate with the template as a key. This option supports multiple aliases. The alias name can include {index}, which is replaced with the name of the index when the index is created.

The object body contains the following optional alias parameters.

mappings

The field mappings that exist in the index. For more information, see Mappings and field types. Optional.

settings

Any configuration options for the index. For more information, see Index settings.

Example requests

The following examples show how to use the Create or Update Index Template API.

Index template with index aliases

The following example request includes index aliases in the template:

PUT /_index_template/alias-template
{
  "index_patterns": [
    "sh*"
  ],
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "aliases": {
      "alias1": {},
      "alias2": {
        "filter": {
          "term": {
            "user.id": "hamlet"
          }
        },
        "routing": "shard-1"
      },
      "{index}-alias": {}
    }
  }
}

response = client.indices.put_index_template(
  name = "alias-template",
  body =   {
    "index_patterns": [
      "sh*"
    ],
    "template": {
      "settings": {
        "number_of_shards": 1
      },
      "aliases": {
        "alias1": {},
        "alias2": {
          "filter": {
            "term": {
              "user.id": "hamlet"
            }
          },
          "routing": "shard-1"
        },
        "{index}-alias": {}
      }
    }
  }
)

Using multiple matching templates

When multiple index templates match the name of a new index or data stream, the template with the highest priority is used. For example, the following two requests create index templates with different priorities.

The first request creates a template with priority 0 that matches index names starting with h:

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

The second request creates a template with priority 1 that matches the narrower set of index names starting with ha:

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

For indexes that start with ha, the _source is enabled. Because only template_two is applied, the index will have two primary shards and one replica.

Overlapping index patterns given the same priority are not allowed. An error will occur when attempting to create a template matching an existing index template with identical priorities.

Adding template versioning

The following example request adds a version number to an index template, which simplifies template management for external systems:

PUT /_index_template/versioned-template
{
  "index_patterns": [
    "mac",
    "cheese"
  ],
  "priority": 0,
  "template": {
    "settings": {
      "number_of_shards": 1
    }
  },
  "version": 1
}

response = client.indices.put_index_template(
  name = "versioned-template",
  body =   {
    "index_patterns": [
      "mac",
      "cheese"
    ],
    "priority": 0,
    "template": {
      "settings": {
        "number_of_shards": 1
      }
    },
    "version": 1
  }
)

Adding template metadata

The following example request uses the _meta parameter to add metadata to the index template. All metadata is stored in the cluster state:

PUT /_index_template/metadata-template
{
  "index_patterns": [
    "rom",
    "juliet"
  ],
  "template": {
    "settings": {
      "number_of_shards": 2
    }
  },
  "_meta": {
    "description": "Where art thou",
    "serialization": {
      "class": "MyIndexTemplate",
      "id": 12
    }
  }
}

response = client.indices.put_index_template(
  name = "metadata-template",
  body =   {
    "index_patterns": [
      "rom",
      "juliet"
    ],
    "template": {
      "settings": {
        "number_of_shards": 2
      }
    },
    "_meta": {
      "description": "Where art thou",
      "serialization": {
        "class": "MyIndexTemplate",
        "id": 12
      }
    }
  }
)

Data stream definition

Include a data_stream object to use an index template for data streams, as shown in the following example request:

PUT /_index_template/logs-template
{
  "index_patterns": [
    "logs-*"
  ],
  "data_stream": {}
}

response = client.indices.put_index_template(
  name = "logs-template",
  body =   {
    "index_patterns": [
      "logs-*"
    ],
    "data_stream": {}
  }
)

Using multiple component templates

When using multiple component templates with the composed_of field, the component templates are merged in the specified order. The settings, mappings, and aliases in the index template’s own template object are merged after the component templates and override them. Settings specified in the create index request override both.

In the following example, an index matching my-index-* has two merged primary shards. If the order in the composed_of array were reversed, then the index would have one primary shard.

First, create a component template that sets one primary shard:

PUT /_component_template/template_with_1_shard
{
  "template": {
    "settings": {
      "index.number_of_shards": 1
    }
  }
}

Next, create a component template that sets two primary shards:

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

Finally, create an index template that composes both component templates in order:

PUT /_index_template/composed-template
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["template_with_1_shard", "template_with_2_shards"]
}

Recursive merging is used for mapping definition and root options such as dynamic_templates and meta, meaning that when an earlier component contains a meta block, new meta entries are added to the end of the metadata in the index. Any entries containing a preexisting key are overwritten.

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: indices:admin/index_template/put.