|
|
@@ -0,0 +1,300 @@
|
|
|
+[[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": ["myindex*"],
|
|
|
+ "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": ["myindex*"],
|
|
|
+ "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" : [
|
|
|
+ "myindex*"
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+---------------------------------------------------------
|
debadair