Simulate index template API

Simulate index template API

New API reference

For the most up-to-date API details, refer to Index APIs.

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

resp = client.indices.simulate_template(
    name="template_1",
)
print(resp)

const response = await client.indices.simulateTemplate({
  name: "template_1",
});
console.log(response);

POST /_index_template/_simulate/template_1

Request

POST /_index_template/_simulate/<index-template>

Prerequisites

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

Path parameters

<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 parameters

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 the master node. If the master node is not available before the timeout expires, the request fails and returns an error. Defaults to 30s. Can also be set to -1 to indicate that the request should never timeout.

include_defaults

(Optional, Boolean) Functionality in [preview] 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. . If true, return all default settings in the response. Defaults to false.

Request body

data_stream

(Optional, object) If this object is included, the template is used to create data streams and their backing indices. Supports an empty object.

Data streams require a matching index template with a data_stream object. See create an index template.

Properties of data_stream

• allow_custom_routing

  (Optional, Boolean) If true, the data stream supports custom routing. Defaults to false.

  hidden

  (Optional, Boolean) If true, the data stream is hidden. Defaults to false.

  index_mode

  (Optional, string) Type of data stream to create. Valid values are null (standard data stream), time_series (time series data stream) and logsdb (logs data stream).

  The template’s index_mode sets the index.mode of the backing index.

index_patterns

(Required, array of strings) Array of wildcard (*) expressions used to match the names of data streams and indices during creation.

Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, see Avoid index pattern collisions.

_meta

(Optional, object) Optional user metadata about the index template. May have any contents. This map is not automatically generated by Elasticsearch.

priority

(Optional, integer) Priority to determine index template precedence when a new data stream or index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though it is of priority 0 (lowest priority). This number is not automatically generated by Elasticsearch.

template

(Optional, object) Template to be applied. It may optionally include an aliases, mappings, or settings configuration.

Properties of template

• aliases

  (Optional, object of objects) Aliases to add.

  If the index template includes a data_stream object, these are data stream aliases. Otherwise, these are index aliases. Data stream aliases ignore the index_routing, routing, and search_routing options.

  Properties of aliases objects

  • <alias>

    (Required, object) The key is the alias name. Index alias names support date math.

    The object body contains options for the alias. Supports an empty object.

    Properties of <alias>

    filter

    (Optional, Query DSL object) Query used to limit documents the alias can access.

    index_routing

    (Optional, string) Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.

    is_hidden

    (Optional, Boolean) If true, the alias is hidden. Defaults to false. All indices for the alias must have the same is_hidden value.

    is_write_index

    (Optional, Boolean) If true, the index is the write index for the alias. Defaults to false.

    routing

    (Optional, string) Value used to route indexing and search operations to a specific shard.

    search_routing

    (Optional, string) Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.

  mappings

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

  • Field names
  • Field data types
  • Mapping parameters

  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 number is not automatically generated by Elasticsearch.

deprecated

(Optional, boolean) Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.

Response body

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, object of objects) Aliases for the index. If the index template includes data_stream, this parameter is not supported.

  Properties of aliases objects

  • <alias>

    (Required, object) The key is the alias name. Index alias names support date math.

    The object body contains options for the alias. Supports an empty object.

    Properties of <alias>

    filter

    (Optional, Query DSL object) Query used to limit documents the alias can access.

    index_routing

    (Optional, string) Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.

    is_hidden

    (Optional, Boolean) If true, the alias is hidden. Defaults to false. All indices for the alias must have the same is_hidden value.

    is_write_index

    (Optional, Boolean) If true, the index is the write index for the alias. Defaults to false.

    routing

    (Optional, string) Value used to route indexing and search operations to a specific shard.

    search_routing

    (Optional, string) Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.

  mappings

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

  • Field names
  • Field data types
  • Mapping parameters

  See Mapping.

  settings

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

Examples

Simulating an existing template

The following example creates and simulates a composed template:

resp = client.cluster.put_component_template(
    name="ct1",
    template={
        "settings": {
            "index.number_of_shards": 2
        }
    },
)
print(resp)
resp1 = client.cluster.put_component_template(
    name="ct2",
    template={
        "settings": {
            "index.number_of_replicas": 0
        },
        "mappings": {
            "properties": {
                "@timestamp": {
                    "type": "date"
                }
            }
        }
    },
)
print(resp1)
resp2 = client.indices.put_index_template(
    name="final-template",
    index_patterns=[
        "my-index-*"
    ],
    composed_of=[
        "ct1",
        "ct2"
    ],
    priority=5,
)
print(resp2)
resp3 = client.indices.simulate_template(
    name="final-template",
)
print(resp3)

response = client.cluster.put_component_template(
  name: 'ct1',
  body: {
    template: {
      settings: {
        'index.number_of_shards' => 2
      }
    }
  }
)
puts response
response = client.cluster.put_component_template(
  name: 'ct2',
  body: {
    template: {
      settings: {
        'index.number_of_replicas' => 0
      },
      mappings: {
        properties: {
          "@timestamp": {
            type: 'date'
          }
        }
      }
    }
  }
)
puts response
response = client.indices.put_index_template(
  name: 'final-template',
  body: {
    index_patterns: [
      'my-index-*'
    ],
    composed_of: [
      'ct1',
      'ct2'
    ],
    priority: 5
  }
)
puts response
response = client.indices.simulate_template(
  name: 'final-template'
)
puts response

const response = await client.cluster.putComponentTemplate({
  name: "ct1",
  template: {
    settings: {
      "index.number_of_shards": 2,
    },
  },
});
console.log(response);
const response1 = await client.cluster.putComponentTemplate({
  name: "ct2",
  template: {
    settings: {
      "index.number_of_replicas": 0,
    },
    mappings: {
      properties: {
        "@timestamp": {
          type: "date",
        },
      },
    },
  },
});
console.log(response1);
const response2 = await client.indices.putIndexTemplate({
  name: "final-template",
  index_patterns: ["my-index-*"],
  composed_of: ["ct1", "ct2"],
  priority: 5,
});
console.log(response2);
const response3 = await client.indices.simulateTemplate({
  name: "final-template",
});
console.log(response3);

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

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

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.

resp = client.indices.simulate_template(
    index_patterns=[
        "my-index-*"
    ],
    composed_of=[
        "ct2"
    ],
    priority=10,
    template={
        "settings": {
            "index.number_of_replicas": 1
        }
    },
)
print(resp)

response = client.indices.simulate_template(
  body: {
    index_patterns: [
      'my-index-*'
    ],
    composed_of: [
      'ct2'
    ],
    priority: 10,
    template: {
      settings: {
        'index.number_of_replicas' => 1
      }
    }
  }
)
puts response

const response = await client.indices.simulateTemplate({
  index_patterns: ["my-index-*"],
  composed_of: ["ct2"],
  priority: 10,
  template: {
    settings: {
      "index.number_of_replicas": 1,
    },
  },
});
console.log(response);

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