Index templatesedit

This documentation is about composable templates. For legacy templates please see the legacy template documentation.

In Elasticsearch 7.8 composable templates were introduced. When a composable template matches a given index it always takes precedence over a legacy template. If no composable template matches, a legacy template may still match and be applied.

An index template is a way to tell Elasticsearch how to configure an index when it is created. Templates are configured prior to index creation and then 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 component templates. Component templates are reusable building blocks that configure mappings, settings, and aliases. You 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.

If a new index matches more than one index template, the index template with the highest priority is used.

If an index is created with explicit settings and also matches an index template, the settings from the create index request take precedence over settings specified in the index template and its component templates.

PUT _component_template/component_template1
{
  "template": {
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT _component_template/other_component_template
{
  "template": {
    "mappings": {
      "properties": {
        "ip_address": {
          "type": "ip"
        }
      }
    }
  }
}

PUT _index_template/template_1
{
  "index_patterns": ["te*", "bar*"],
  "template": {
    "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"
        }
      }
    },
    "aliases": {
      "mydata": { }
    }
  },
  "priority": 10,
  "composed_of": ["component_template1", "other_component_template"],
  "version": 3,
  "_meta": {
    "description": "my custom"
  }
}

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.