Index templates

Index templates let you initialize new indices with predefined mappings and settings. For example, if you continuously index log data, you can define an index template so that all of these indices have the same number of shards and replicas.

Create a template

To create an index template, use a POST request:

  1. POST _index_template

This command creates a template named daily_logs and applies it to any new index whose name matches the regular expression logs-2020-01-* and also adds it to the my_logs alias:

  1. PUT _index_template/daily_logs
  2. {
  3.   "index_patterns": [
  4.     "logs-2020-01-*"
  5.   ],
  6.   "template": {
  7.     "aliases": {
  8.       "my_logs": {}
  9.     },
  10.     "settings": {
  11.       "number_of_shards": 2,
  12.       "number_of_replicas": 1
  13.     },
  14.     "mappings": {
  15.       "properties": {
  16.         "timestamp": {
  17.           "type": "date",
  18.           "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
  19.         },
  20.         "value": {
  21.           "type": "double"
  22.         }
  23.       }
  24.     }
  25.   }
  26. }

You should see the following response:

  1. {
  2.   "acknowledged": true
  3. }

If you create an index named logs-2020-01-01, you can see that it has the mappings and settings from the template:

  1. PUT logs-2020-01-01
  2. GET logs-2020-01-01
  1. {
  2.   "logs-2020-01-01": {
  3.     "aliases": {
  4.       "my_logs": {}
  5.     },
  6.     "mappings": {
  7.       "properties": {
  8.         "timestamp": {
  9.           "type": "date",
  10.           "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
  11.         },
  12.         "value": {
  13.           "type": "double"
  14.         }
  15.       }
  16.     },
  17.     "settings": {
  18.       "index": {
  19.         "creation_date": "1578107970779",
  20.         "number_of_shards": "2",
  21.         "number_of_replicas": "1",
  22.         "uuid": "U1vMDMOHSAuS2IzPcPHpOA",
  23.         "version": {
  24.           "created": "7010199"
  25.         },
  26.         "provided_name": "logs-2020-01-01"
  27.       }
  28.     }
  29.   }
  30. }

Any additional indices that match this pattern—logs-2020-01-02, logs-2020-01-03, and so on—will inherit the same mappings and settings.

Retrieve a template

To list all index templates:

  1. GET _cat/templates

To find a template by its name:

  1. GET _index_template/daily_logs

To get a list of all your templates:

  1. GET _index_template/daily_logs

To get a list of all templates that match a pattern:

  1. GET _index_template/daily*

To check if a specific template exists:

  1. HEAD _index_template/<name>

Configure multiple templates

You can create multiple index templates for your indices. If the index name matches more than one template, OpenSearch merges all mappings and settings from all matching templates and applies them to the index.

The settings from the more recently created index templates override the settings of older index templates. So, you can first define a few common settings in a generic template that can act as a catch-all and then add more specialized settings as required.

An even better approach is to explicitly specify template priority using the order parameter. OpenSearch applies templates with lower priority numbers first and then overrides them with templates with higher priority numbers.

For example, say you have the following two templates that both match the logs-2020-01-02 index and there’s a conflict in the number_of_shards field:

Template 1

  1. PUT _index_template/template-01
  2. {
  3.   "index_patterns": [
  4.     "logs*"
  5.   ],
  6.   "priority": 0,
  7.   "template": {
  8.     "settings": {
  9.       "number_of_shards": 2
  10.     }
  11.   }
  12. }

Template 2

  1. PUT _index_template/template-02
  2. {
  3.   "index_patterns": [
  4.     "logs-2020-01-*"
  5.   ],
  6.   "priority": 1,
  7.   "template": {
  8.     "settings": {
  9.       "number_of_shards": 3
  10.     }
  11.   }
  12. }

Because template-02 has a higher priority value, it takes precedence over template-01 . The logs-2020-01-02 index would have the number_of_shards value as 3.

Delete a template

You can delete an index template using its name:

  1. DELETE _index_template/daily_logs

Composable index templates

Managing multiple index templates has the following challenges:

  • If you have duplication between index templates, storing these index templates results in a bigger cluster state.
  • If you want to make a change across all your index templates, you have to manually make the change for each template.
  • If an index matches multiple templates, OpenSearch might merge the templates in an unexpected way that you discover only after an index is created.

You can use composable index templates to overcome these challenges. Composable index templates let you abstract common settings, mappings, and aliases into a reusable building block called a component template.

You can combine component templates to compose an index template.

Settings and mappings that you specify directly in the create index request override any settings or mappings specified in an index template and its component templates.

Create a component template

Let’s define two component templates⁠—component_template_1 and component_template_2:

Component template 1

  1. PUT _component_template/component_template_1
  2. {
  3.   "template": {
  4.     "mappings": {
  5.       "properties": {
  6.         "@timestamp": {
  7.           "type": "date"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }

Component template 2

  1. PUT _component_template/component_template_2
  2. {
  3.   "template": {
  4.     "mappings": {
  5.       "properties": {
  6.         "ip_address": {
  7.           "type": "ip"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }

Use component templates to create an index template

When creating index templates, you need to include the component templates in a composed_of list.

OpenSearch applies the component templates in the order in which you specify them within the index template. The settings, mappings, and aliases that you specify inside the index template are applied last.

  1. PUT _index_template/daily_logs
  2. {
  3.   "index_patterns": [
  4.     "logs-2020-01-*"
  5.   ],
  6.   "template": {
  7.     "aliases": {
  8.       "my_logs": {}
  9.     },
  10.     "settings": {
  11.       "number_of_shards": 2,
  12.       "number_of_replicas": 1
  13.     },
  14.     "mappings": {
  15.       "properties": {
  16.         "timestamp": {
  17.           "type": "date",
  18.           "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
  19.         },
  20.         "value": {
  21.           "type": "double"
  22.         }
  23.       }
  24.     }
  25.   },
  26.   "priority": 200,
  27.   "composed_of": [
  28.     "component_template_1",
  29.     "component_template_2"
  30.   ],
  31.   "version": 3,
  32.   "_meta": {
  33.     "description": "using component templates"
  34.   }
  35. }

If you create an index named logs-2020-01-01, you can see that it derives its mappings and settings from both the component templates:

  1. PUT logs-2020-01-01
  2. GET logs-2020-01-01

Sample response

  1. {
  2.   "logs-2020-01-01": {
  3.     "aliases": {
  4.       "my_logs": {}
  5.     },
  6.     "mappings": {
  7.       "properties": {
  8.         "@timestamp": {
  9.           "type": "date"
  10.         },
  11.         "ip_address": {
  12.           "type": "ip"
  13.         },
  14.         "timestamp": {
  15.           "type": "date",
  16.           "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
  17.         },
  18.         "value": {
  19.           "type": "double"
  20.         }
  21.       }
  22.     },
  23.     "settings": {
  24.       "index": {
  25.         "creation_date": "1625382479459",
  26.         "number_of_shards": "2",
  27.         "number_of_replicas": "1",
  28.         "uuid": "rYUlpOXDSUSuZifQLPfa5A",
  29.         "version": {
  30.           "created": "7100299"
  31.         },
  32.         "provided_name": "logs-2020-01-01"
  33.       }
  34.     }
  35.   }
  36. }

Simulate multi-component templates

For index templates composed of multiple component templates, you can simulate applying a new template to verify whether the settings are applied as you expect.

To simulate the settings that would be applied to a specific index name:

  1. POST _index_template/_simulate_index/<index_name>

To simulate the settings that would be applied from an existing template:

  1. POST _index_template/_simulate/<index_template>

You can also specify a template definition in the simulate request:

  1. POST _index_template/_simulate
  2. {
  3.   "index_patterns": [
  4.     "logs-2020-01-*"
  5.   ],
  6.   "template": {
  7.     "settings" : {
  8.         "index.number_of_shards" : 3
  9.     }
  10.   },
  11.   "composed_of": ["component_template_1", "component_template_2"]
  12. }

The _simulate API returns the final settings, mappings, and aliases that will be applied to indices that match the index pattern. You can also see any overlapping templates whose configuration is superseded by the simulated template body or higher priority templates:

  1. {
  2.   "template" : {
  3.     "settings" : {
  4.       "index" : {
  5.         "number_of_shards" : "3"
  6.       }
  7.     },
  8.     "mappings" : {
  9.       "properties" : {
  10.         "@timestamp" : {
  11.           "type" : "date"
  12.         },
  13.         "ip_address" : {
  14.           "type" : "ip"
  15.         }
  16.       }
  17.     },
  18.     "aliases" : { }
  19.   },
  20.   "overlapping" : [
  21.     {
  22.       "name" : "daily_logs",
  23.       "index_patterns" : [
  24.         "logs-2020-01-*"
  25.       ]
  26.     }
  27.   ]
  28. }

Index template options

You can specify the following template options:

OptionTypeDescriptionRequired
templateObjectSpecify index settings, mappings, and aliases.No
priorityIntegerThe priority of the index template.No
composed_ofString arrayThe names of component templates applied on a new index together with the current template.No
versionIntegerSpecify a version number to simplify template management. Default is null.No
_metaObjectSpecify meta information about the template.No