Index templates

edit

This topic describes the composable index templates introduced in Elasticsearch 7.8. For information about how index templates worked previously, see the legacy template documentation.

An index template is a way to tell Elasticsearch 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 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 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.

Create index template

edit

Use the index template and put component template APIs to create and update index templates. You can also manage index templates from Stack Management in Kibana.

The following requests create two component templates.

response = client.cluster.put_component_template(
  name: 'component_template1',
  body: {
    template: {
      mappings: {
        properties: {
          "@timestamp": {
            type: 'date'
          }
        }
      }
    }
  }
)
puts response

response = client.cluster.put_component_template(
  name: 'runtime_component_template',
  body: {
    template: {
      mappings: {
        runtime: {
          day_of_week: {
            type: 'keyword',
            script: {
              source: "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
            }
          }
        }
      }
    }
  }
)
puts response
PUT _component_template/component_template1
{
  "template": {
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT _component_template/runtime_component_template
{
  "template": {
    "mappings": {
      "runtime": { 
        "day_of_week": {
          "type": "keyword",
          "script": {
            "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
          }
        }
      }
    }
  }
}

This component template adds a 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.

response = client.indices.put_index_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'te*',
      'bar*'
    ],
    template: {
      settings: {
        number_of_shards: 1
      },
      mappings: {
        _source: {
          enabled: true
        },
        properties: {
          host_name: {
            type: 'keyword'
          },
          created_at: {
            type: 'date',
            format: 'EEE MMM dd HH:mm:ss Z yyyy'
          }
        }
      },
      aliases: {
        mydata: {}
      }
    },
    priority: 500,
    composed_of: [
      'component_template1',
      'runtime_component_template'
    ],
    version: 3,
    _meta: {
      description: 'my custom'
    }
  }
)
puts response
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",
          "format": "EEE MMM dd HH:mm:ss Z yyyy"
        }
      }
    },
    "aliases": {
      "mydata": { }
    }
  },
  "priority": 500,
  "composed_of": ["component_template1", "runtime_component_template"], 
  "version": 3,
  "_meta": {
    "description": "my custom"
  }
}