elasticsearch/docs/reference/indices/index-templates.asciidoc

[[index-templates]]
= Index templates

NOTE: This topic describes the composable index templates introduced in {es} 7.8.
For information about how index templates worked previously,
see the <<indices-templates-v1,legacy template documentation>>.

[[getting]]
An index template is a way to tell {es} how to configure an index when it is
created. For data streams, the index template configures the stream's backing
indices as they are created. Templates are configured
*prior to index creation*. When an index is created - either manually or
through indexing a document - the template settings are used as a basis for
creating the index.

There are two types of templates: index templates and <<indices-component-template,component templates>>. Component templates are reusable building
blocks that configure mappings, settings, and aliases. While you can use
component templates to construct index templates, they aren't directly applied
to a set of indices. Index templates can contain a collection of component
templates, as well as directly specify settings, mappings, and aliases.

The following conditions apply to index templates:

* Composable templates take precedence over legacy templates. If no composable
template matches a given index, a legacy template may still match and be
applied.
* If an index is created with explicit settings and also matches an index
template, the settings from the <<indices-create-index,create index>> request
take precedence over settings specified in the index template and its component
templates.
* Settings specified in the index template itself take precedence over the settings
in its component templates.
* If a new data stream or index matches more than one index template, the index
template with the highest priority is used.

[[avoid-index-pattern-collisions]]
.Avoid index pattern collisions
****
{es} has built-in index templates, each with a priority of `100`, for the
following index patterns:

// tag::built-in-index-template-patterns[]
- `logs-*-*`
- `metrics-*-*`
- `synthetics-*-*`
- `profiling-*`
- `security_solution-*-*`
// end::built-in-index-template-patterns[]

{fleet-guide}/fleet-overview.html[{agent}] uses these templates to create
data streams. Index templates created by {fleet} integrations use similar
overlapping index patterns and have a priority up to `200`.

If you use {fleet} or {agent}, assign your index templates a priority lower than
`100` to avoid overriding these templates. Otherwise, to avoid accidentally
applying the templates, do one or more of the following:

- To disable all built-in index and component templates, set
<<stack-templates-enabled,`stack.templates.enabled`>> to `false` using the
<<cluster-update-settings,cluster update settings API>>.

- Use a non-overlapping index pattern.

- Assign templates with an overlapping pattern a `priority` higher than `500`.
For example, if you don't use {fleet} or {agent} and want to create a template
for the `logs-*` index pattern, assign your template a priority of `500`. This
ensures your template is applied instead of the built-in template for
`logs-*-*`.

- To avoid naming collisions with built-in and Fleet-managed index templates, avoid using `@` as part of the name of your own index templates.
****

[discrete]
[[create-index-templates]]
== Create index template

Use the <<indices-put-template,index template>> and <<indices-component-template,put component template>> APIs to create and update index templates.
You can also <<index-mgmt,manage index templates>> from Stack
Management in {kib}.

The following requests create two component templates.

[source,console]
----
PUT _component_template/component_template1
{
  "template": {
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT _component_template/runtime_component_template
{
  "template": {
    "mappings": {
      "runtime": { <1>
        "day_of_week": {
          "type": "keyword",
          "script": {
            "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
          }
        }
      }
    }
  }
}
----
<1> This component template adds a <<runtime-mapping-fields,runtime field>>
named `day_of_week` to the mappings when a new index matches the template.

The following request creates an index template that is _composed of_ these
component templates.

[source,console]
----
PUT _index_template/template_1
{
  "index_patterns": ["te*", "bar*"],
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "mappings": {
      "_source": {
        "enabled": true
      },
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date"
        }
      }
    },
    "aliases": {
      "mydata": { }
    }
  },
  "priority": 500,
  "composed_of": ["component_template1", "runtime_component_template"], <1>
  "version": 3,
  "_meta": {
    "description": "my custom"
  }
}
----
// TEST[continued]

////

[source,console]
----
DELETE _index_template/template_1
DELETE _component_template/runtime_component_template
DELETE _component_template/component_template1
----
// TEST[continued]

////

include::simulate-multi-component-templates.asciidoc[]

include::ignore-missing-component-templates.asciidoc[]