Template priority and composition in Elasticsearch

Introduction

Templates help you reuse search or index settings easily. Priority and composition decide which templates apply when multiple templates match.

You want to apply different settings to indexes based on their names.

You have multiple templates and want to control which one is used first.

You want to combine settings from several templates for an index.

You want to update or add settings without rewriting all templates.

You want to manage templates in a clear order to avoid conflicts.

Syntax

Elasticsearch

PUT _index_template/template_name
{
  "index_patterns": ["pattern*"],
  "priority": number,
  "composed_of": ["template1", "template2"],
  "template": {
    "settings": { ... },
    "mappings": { ... },
    "aliases": { ... }
  }
}

priority is a number. Higher means this template applies first.

composed_of lets you combine other templates by name.

Examples

This template applies to indexes starting with 'logs-' and sets 1 shard.

Elasticsearch

PUT _index_template/base_template
{
  "index_patterns": ["logs-*"],
  "priority": 5,
  "template": {
    "settings": {
      "number_of_shards": 1
    }
  }
}

This template has higher priority and applies to 'logs-2024*' indexes, setting replicas to 2.

Elasticsearch

PUT _index_template/high_priority_template
{
  "index_patterns": ["logs-2024*"],
  "priority": 10,
  "template": {
    "settings": {
      "number_of_replicas": 2
    }
  }
}

This template combines two templates and adds a refresh interval setting.

Elasticsearch

PUT _index_template/composed_template
{
  "index_patterns": ["logs-2024*"],
  "priority": 15,
  "composed_of": ["base_template", "high_priority_template"],
  "template": {
    "settings": {
      "refresh_interval": "30s"
    }
  }
}

Sample Program

This example creates three templates. The last one combines the first two and adds a refresh interval. When you create an index named 'app-2024-01', Elasticsearch applies the composed template with the highest priority. The index will have 2 shards, 1 replica, a refresh interval of 1 second, and mappings for 'user' and 'timestamp'.

Elasticsearch

PUT _index_template/base_template
{
  "index_patterns": ["app-*"],
  "priority": 5,
  "template": {
    "settings": {
      "number_of_shards": 2
    },
    "mappings": {
      "properties": {
        "user": { "type": "keyword" }
      }
    }
  }
}

PUT _index_template/high_priority_template
{
  "index_patterns": ["app-2024*"],
  "priority": 10,
  "template": {
    "settings": {
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "timestamp": { "type": "date" }
      }
    }
  }
}

PUT _index_template/composed_template
{
  "index_patterns": ["app-2024*"],
  "priority": 15,
  "composed_of": ["base_template", "high_priority_template"],
  "template": {
    "settings": {
      "refresh_interval": "1s"
    }
  }
}

GET app-2024-01/_settings
GET app-2024-01/_mapping

Important Notes

Templates with higher priority override settings from lower priority templates.

When using composed_of, the order of templates matters for merging.

Always test your templates by creating a new index and checking its settings and mappings.

Summary

Templates let you reuse index settings and mappings easily.

Priority controls which template applies first when multiple match.

Composition lets you combine templates for flexible configuration.