IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Elastic Docs ›Elasticsearch Guide [7.10] ›REST APIs ›Index APIs
« Simulate index API Split index API »

Simulate index template APIedit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Returns the index configuration that would be applied by a particular index template.

POST /_index_template/_simulate/template_1

Requestedit

POST /_index_template/_simulate/<index-template>

Prerequisitesedit

  • If the Elasticsearch security features are enabled, you must have the manage_index_templates or manage cluster privilege to use this API.

Path parametersedit

<index-template>
(Optional, string) Name of the index template to simulate. To test a template configuration before you add it to the cluster, omit this parameter and specify the template configuration in the request body.

Query parametersedit

create
(Optional, Boolean) If true, the template passed in the body is only used if no existing templates match the same index patterns. If false, the simulation uses the template with the highest priority. Note that the template is not permanently added or updated in either case; it is only used for the simulation. Defaults to false.
master_timeout
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Request bodyedit

composed_of
(Optional, array of strings) Ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence. For an example, see Composing multiple component templates.
index_patterns
(Required, array of strings) Array of wildcard (*) expressions used to match the names of indices during creation.
priority
(Optional, integer) Priority that determines what template is applied if there are multiple templates that match the name of a new index. The highest priority template takes precedence. Defaults to 0 (lowest priority).
template

(Optional, object) Template to apply.

Properties of template
aliases
(Optional, alias object) Index aliases which include the index. See Update index alias.
mappings

(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:

See Mapping.

settings
(Optional, index setting object) Configuration options for the index. See Index Settings.
version
(Optional, integer) Version number used to manage index templates externally. This version is not automatically generated by Elasticsearch.
_meta
(Optional, object) User-specified metadata for the index template. This information is not generated or used by Elasticsearch.

Response bodyedit

overlapping

(array) Any templates that were superseded by the specified template.

Properties of overlapping
index_patterns
(array) Index patterns that the superseded template applies to.
name
(string) Name of the superseded template.
template

(object) The settings, mappings, and aliases that would be applied to matching indices.

Properties of template
aliases
(Optional, alias object) Index aliases which include the index. See Update index alias.
mappings

(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:

See Mapping.

settings
(Optional, index setting object) Configuration options for the index. See Index Settings.

Examplesedit

Simulating an existing templateedit

The following example creates and simulates a composed template:

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": ["my-index-*"],
  "composed_of": ["ct1", "ct2"],
  "priority": 5
}

POST /_index_template/_simulate/final-template

Create a component template (ct1) that sets the number of shards to 2

Create a component template (ct2) that sets the number of replicas to 0 and defines a mapping

Create an index template (final-template) that uses the component templates

Show the configuration applied by the final-template

The response shows the index settings, mappings, and aliases applied by the final-template:

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_shards" : "2",  
        "number_of_replicas" : "0" 
      }
    },
    "mappings" : {                 
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [ ]
}

Number of shards from ct1

Number of replicas from ct2

Mappings from ct1

Simulating an arbitrary template configurationedit

To see what settings will be applied by a template before you add it to the cluster, you can pass a template configuration in the request body. The specified template is used for the simulation if it has a higher priority than existing templates.

POST /_index_template/_simulate
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["ct2"],
  "priority": 10,
  "template": {
    "settings": {
      "index.number_of_replicas": 1
    }
  }
}

The response shows any overlapping templates with a lower priority.

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_replicas" : "1"
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "final-template",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}
« Simulate index API Split index API »