OpenSearch/docs/reference/indices/simulate-template.asciidoc

[[indices-simulate-template]]
=== Simulate index template API
++++
<titleabbrev>Simulate template</titleabbrev>
++++

experimental[]

Returns the index configuration that would be applied by a particular 
<<indices-templates, index template>>.

////
[source,console]
--------------------------------------------------
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,
  "version": 3,
  "_meta": {
    "description": "my custom"
  }
}
--------------------------------------------------
// TESTSETUP

[source,console]
--------------------------------------------------
DELETE _index_template/*
DELETE _component_template/*
--------------------------------------------------
// TEARDOWN
////

[source,console]
--------------------------------------------------
POST /_index_template/_simulate/template_1
--------------------------------------------------

[[simulate-template-api-request]]
==== {api-request-title}

`POST /_index_template/_simulate/<index-template>`


[[simulate-template-api-path-params]]
==== {api-path-parms-title}

`<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.

[[simulate-template-api-query-params]]
==== {api-query-parms-title}
////
`cause`::
(Optional, string) The reason for using the specified template for the simulation. 
////

`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`.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

[[simulate-template-api-request-body]]
==== {api-request-body-title}

`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 
<<multiple-component-templates,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`
[%collapsible%open]
====
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
====

`version`::
(Optional, integer)
Version number used to manage index templates externally.
This version is not automatically generated by {es}.

`_meta`::
(Optional, object)
User-specified metadata for the index template. 
This information is not generated or used by {es}.

[role="child_attributes"]
[[simulate-template-api-response-body]]
==== {api-response-body-title}

`overlapping`::
(array) Any templates that were superseded by the specified template.
+
.Properties of `overlapping`
[%collapsible%open]
====
`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`
[%collapsible%open]
====
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
====

[[simulate-template-api-example]]
==== {api-examples-title}

[[simulate-existing-template-ex]]
===== Simulating an existing template

The following example creates and simulates a composed template:

[source,console]
--------------------------------------------------
PUT /_component_template/ct1                   <1>
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/ct2                    <2>
{
  "template": {
    "settings": {
      "index.number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT /_index_template/final-template            <3>
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["ct1", "ct2"],
  "priority": 5
}

POST /_index_template/_simulate/final-template <4>
--------------------------------------------------
<1> Create a component template (`ct1`) that sets the number of shards to 2
<2> Create a component template (`ct2`) that sets the number of replicas to 0 and defines a mapping
<3> Create an index template (`final-template`) that uses the component templates
<4> Show the configuration applied by the `final-template`

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

[source,console-result]
---------------------------------------------------------
{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_shards" : "2",  <1>
        "number_of_replicas" : "0" <2>
      }
    },
    "mappings" : {                 <3>
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [ ]
}
---------------------------------------------------------
<1> Number of shards from `ct1`
<2> Number of replicas from `ct2`
<3> Mappings from `ct1`


[[simulate-template-config-ex]]
===== Simulating an arbitrary template configuration

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.

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

The response shows any overlapping templates with a lower priority.

[source,console-result]
---------------------------------------------------------
{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_replicas" : "1"
      }
    },
    "mappings" : {
      "properties" : { 
        "@timestamp" : {           
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "final-template",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}
---------------------------------------------------------