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

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

Returns the index configuration that would be applied by a particular
<<index-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"
        }
      }
    },
    "aliases": {
      "mydata": { }
    }
  },
  "priority": 10,
  "version": 3,
  "_meta": {
    "description": "my custom"
  }
}
--------------------------------------------------
// TESTSETUP

[source,console]
--------------------------------------------------
DELETE _index_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-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
privilege>> to use this API.

[[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]

`include_defaults`::
(Optional, Boolean) Functionality in preview:[]. If `true`, return all default settings in the response.
Defaults to `false`.

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

include::{es-ref-dir}/indices/put-index-template.asciidoc[tag=index-template-api-body]

[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]
====
`aliases`::
(Optional, object of objects) Aliases for the index. If the index template
includes `data_stream`, this parameter is not supported.
+
include::{es-ref-dir}/indices/create-index.asciidoc[tag=aliases-props]

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>
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "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",
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "final-template",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}
---------------------------------------------------------