How do you verify which Elasticsearch template will apply to an index before it is created?
answer
- ask before the index exists
- one endpoint takes a name, one takes a template
- the response also names the losers
- attach it to code review, not to firefighting
basics
~20 sCall POST _index_template/_simulate_index/<name>. Elasticsearch resolves that name against every stored template and returns the settings, mappings and aliases the index would actually receive, plus an overlapping list naming the templates that matched but lost on priority.
solid answer
~50 sThere are two simulate endpoints and they answer different questions. `POST _index_template/_simulate_index/<index-name>` takes an **index name**, which need not exist, resolves the priority contest, performs the whole composition, and returns the composed `settings`, `mappings` and `aliases` together with an `overlapping` array listing other templates that matched the name and their patterns. That is the one to reach for when an index came out wrong, or before a rollover creates the next backing index. `POST _index_template/_simulate/<template-name>` takes a **template**, and can also accept an unsaved template definition in the request body, so you can see how a proposed change composes before you store it. Both are read-only. The habit worth building is to assert on simulate output in CI: apply the templates to a test cluster, simulate the names you actually create, and diff the composed mapping against a checked-in expectation. Template mistakes are otherwise invisible until an index is born with them, and by then fixing it costs a reindex.
code
bash · 11 lines# what would this future index actually get?
POST _index_template/_simulate_index/logs-app-2024.06.02
# how does a template I have not saved yet compose?
POST _index_template/_simulate
{
"index_patterns": ["logs-app-*"],
"priority": 500,
"composed_of": ["base-settings", "common-fields"],
"template": { "mappings": { "properties": { "level": { "type": "keyword" } } } }
}go deeper
Know that a simulate API exists and that you can ask what configuration an index name would receive before creating it. Being able to name the endpoint shape is enough here.
Distinguish the two endpoints - one resolves an index name including the priority contest, the other composes a template definition - and read the overlapping section to explain why a template lost.
Use it as a diagnostic reflex when an index comes out wrong, and know its limits: an existing index's own mapping and settings are authoritative and can legitimately differ from what simulate predicts.
Turn it into a gate. Composed mappings diffed against golden files in CI turn a class of silent, reindex-expensive template mistakes into build failures, and give reviewers the effective mapping as the artefact.
## The gap simulate closes An index template is evaluated exactly once, when an index is created, and the result is silent. If your `index_patterns` has a typo, nothing errors — the index is simply created with defaults and dynamic mapping. If another team's template outranks yours on priority, nothing errors either — the index is created with their configuration. Both failures are only visible in the mapping of an index that already exists, at which point the field types are frozen and the remedy is a reindex. The simulate APIs exist to move that discovery earlier, to the moment you are editing the template. ## _simulate_index — "what will this name get?" `POST _index_template/_simulate_index/<index-name>` is the diagnostic workhorse. You give it an index name; the name does not have to exist and usually should not. Elasticsearch does the full resolution: 1. finds every index template whose `index_patterns` match the name, 2. selects the winner by `priority`, 3. merges the winner's `composed_of` components in order, then its own `template` block, 4. returns the composed `settings`, `mappings` and `aliases`. Alongside the composed result it returns an `overlapping` array: the other templates that matched the name, each with its `index_patterns`. That section is the answer to "why did my template not apply?" — if your template's name is in `overlapping` rather than being the one that produced the composed result, it lost the priority contest, and you now know exactly to whom. Because it accepts a name rather than a template, this endpoint is the right call before a rollover: simulate the next backing index name and confirm it will come out the way you expect. ## _simulate — "what does this template compose to?" `POST _index_template/_simulate/<template-name>` composes a stored template and returns the result. More usefully, you can `POST _index_template/_simulate` with a template definition **in the body**, which composes a template you have not stored yet — including the effect of any `composed_of` components that do exist. That is the pre-merge review tool: paste the proposed template, see the mapping it will produce, and attach the output to the change request. Note the difference in what each answers. `_simulate` tells you what one template composes to. It does **not** tell you whether that template would actually win for a given index name; only `_simulate_index` runs the priority contest. ## After the fact Once an index exists, simulate is no longer the tool — the index's own metadata is authoritative and may differ from any template, because a create-index request body can override the whole stack and because settings can be changed on a live index afterwards. Use `GET /<index>/_mapping` and `GET /<index>/_settings` for what an index really has, and reserve simulate for what an index *would* get. Comparing the two is itself a useful drift check: if a long-lived index disagrees with the simulate output for its own name, someone overrode the template or updated the index directly. To see the inputs rather than the outputs, `GET _index_template` and `GET _component_template` list the stored definitions, including each template's `priority`, `version` and `_meta`, and both accept a name pattern (`GET _index_template/logs*`) so you can survey a namespace quickly. ## Making it a gate rather than a habit The strongest version of this practice is automated. Templates live in version control as JSON; a pipeline applies them to a disposable or staging cluster, calls `_simulate_index` for each index name pattern the system actually creates, and diffs the composed mapping against a checked-in golden file. A change that silently drops a field, flips `keyword` to `text`, or gets outranked by a newly installed integration template fails the build instead of failing production. Because the composed output is deterministic and version-controlled, the diff also becomes the review artefact: reviewers read the effective mapping, which is what they care about, rather than trying to simulate a multi-layer merge in their heads.
- What is in the overlapping section of a _simulate_index response, and why does it matter?It lists the other templates whose index_patterns also matched the name, with their patterns. If your template appears there rather than producing the composed result, it matched but lost the priority contest — which turns a mysterious wrong mapping into a specific, attributable conflict you can fix by adjusting priority.
- Can you simulate a template you have not saved yet?Yes. POST _index_template/_simulate accepts a template definition in the request body and returns what it composes to, including the contribution of existing component templates. That makes it a pre-merge review tool: reviewers read the effective mapping instead of mentally merging several layers.
- An index already exists and disagrees with the simulate output for its name. What does that tell you?That something bypassed the template: an explicit create-index body overrode it, a live settings update changed it afterwards, or the templates have been edited since the index was born. The index metadata is authoritative for what it has; simulate only says what a new index would get.
saying these in an interview costs you the question
- Checks the template JSON by eye instead of simulating
- Uses _simulate when the question is which template wins for a name
- Assumes an existing index still matches its template's output
- Treats simulate as a write operation that changes configuration
- Only simulates after an index has already been created wrong