skip to content

When several Elasticsearch index templates match a new index name, which one wins?

level: middleimportance: must knowfreq 62%

answer

  1. several may match, one is chosen
  2. a number decides, not pattern length
  3. ties are refused when you save
  4. default value of that number is zero

basics

~20 s

Exactly one composable index template is applied: the matching one with the highest priority. Elasticsearch refuses to store two templates whose index_patterns overlap at the same priority, so ties are prevented when you save the template rather than resolved at index creation.

solid answer

~50 s

With composable templates there is no merging *between* index templates — Elasticsearch picks a single winner. Every matching template is ranked by its `priority` field, which defaults to `0`, and the highest one applies; the losers contribute nothing at all, not even fields the winner leaves undefined. Ties cannot happen at index time because the cluster validates on `PUT`: storing a template whose `index_patterns` overlap an existing template with the same priority is rejected with an error telling you to choose a different priority. Two consequences matter in practice. First, a more specific pattern does **not** automatically beat a broader one — `logs-app-*` loses to `logs-*` if `logs-*` has the higher number, so specificity has to be expressed as priority. Second, Elastic ships built-in templates for patterns such as `logs-*-*` and `metrics-*-*`; if you want your own template to govern those names you must give it a priority above the built-in one, which you can read with `GET _index_template`.

code

bash · 12 lines
bash
# broad family default
PUT _index_template/orders-base
{ "index_patterns": ["orders-*"], "priority": 100,
  "template": { "settings": { "number_of_shards": 1 } } }

# refinement that must beat it
PUT _index_template/orders-eu
{ "index_patterns": ["orders-eu-*"], "priority": 200,
  "template": { "settings": { "number_of_shards": 6 } } }

# which one claims a given name?
POST _index_template/_simulate_index/orders-eu-2024

go deeper

for a junior

Remember the headline: one template wins, chosen by the priority number, and priority defaults to zero. That alone answers the question at a screening interview.

for a middle

Explain that losers contribute nothing, that overlapping patterns at equal priority are rejected at PUT time, and that specificity has no built-in meaning. Be ready to reason about a concrete pair of templates.

for a senior

Show how you diagnose a wrong-looking index: simulate the name, read the overlapping list, check the priorities of Elastic's shipped templates. Mention the risk of a catch-all pattern claiming system indices.

for a principal

Own the priority scheme itself. Reserve documented bands per tier so teams can add templates without collisions, and decide the policy for coexisting with vendor-managed templates in the same namespace.

## One winner, not a merge The rule for composable index templates is deliberately blunt: **for any new index, exactly one index template applies.** Elasticsearch collects every template whose `index_patterns` match the index name, sorts them by `priority`, and uses the highest. The runners-up are discarded entirely. This is worth stating precisely because it is the opposite of what many candidates expect and the opposite of how the older legacy templates behaved. If template A (`logs-*`, priority 200) defines an analyzer and template B (`logs-app-*`, priority 100) defines a mapping, an index called `logs-app-1` gets A's analyzer and **none** of B's mapping. There is no field-level fallback to the loser. Composition happens *within* the winning template — across its `composed_of` component templates — never *between* competing index templates. ## priority and the tie rule `priority` is a plain non-negative integer stored on the template and defaults to `0` if you omit it. Higher wins. Ties are not resolved at index-creation time because they cannot arise: when you `PUT` an index template whose patterns overlap those of an existing template at the same priority, the request is rejected. The error explains that multiple templates could match during index creation and asks you to use a different priority. This is a genuinely good design decision — the ambiguity is caught by the person deploying the template, in a request that fails loudly, instead of by an on-call engineer three weeks later looking at an index with the wrong shard count. Note that overlap is judged on the *patterns*, not on whether any index actually exists. `logs-*` and `logs-app-*` overlap; `logs-*` and `metrics-*` do not, so both may sit at priority 0 quite happily. ## Specificity is not automatic There is no rule that a narrower pattern beats a wider one. Elasticsearch does not measure pattern specificity at all; it reads a number. If you want the intuitive behaviour — the most specific template governs — you must encode it yourself by assigning priorities in bands, for example: - broad catch-alls for a whole family: priority 100 - per-application refinements: priority 200 - per-environment or emergency overrides: priority 500 Document the bands somewhere a human will find them. A team that assigns priorities ad hoc ends up unable to add a template at all, because every free number collides with something. ## Built-in and managed templates A stock Elasticsearch cluster is not empty of templates. Elastic ships templates for observability-style patterns such as `logs-*-*` and `metrics-*-*`, and installing integrations adds more. These carry their own priorities, which you can inspect with `GET _index_template` (or `GET _index_template/logs*`) and read from the `priority` field of each entry. If your data lands on one of those patterns, your template must sit above the shipped one or it will simply never apply — and because a template that never applies produces no error, the symptom is an index that quietly has somebody else's mapping. The complementary discipline is to avoid claiming names you do not own. A template with `index_patterns: ["*"]` at a high priority is a cluster-wide landmine: it wins for every index in the system, including internal ones you did not think about. ## Composable versus legacy precedence Old-style templates registered under `_template` participate in a separate, lower-precedence tier. If **any** composable index template matches the new index name, the legacy templates are ignored completely; legacy templates are only consulted when no composable template matches. This means the migration path is safe in one direction and confusing in the other: adding a composable template silently switches an index family away from a legacy template that may still be configuring things you rely on. ## Diagnosing it When an index comes out with the wrong configuration, do not guess which template won. `POST _index_template/_simulate_index/<name>` resolves the name against all stored templates and returns both the composed result and an `overlapping` list naming the templates that matched but lost, with their patterns. That output answers "which template won and what else nearly did" in one call, and it works for index names that do not exist yet, which is exactly the case you want to check before the next rollover creates one.

  • Does a more specific index_patterns entry automatically beat a broader one?
    No. Elasticsearch never measures pattern specificity; it compares priority integers only. If logs-* has a higher priority than logs-app-*, the broad template governs logs-app-1 and the specific one contributes nothing. You must encode specificity yourself with deliberate priority bands.
  • The losing template defines a field the winner does not. Does that field still get mapped?
    No. Losing index templates contribute nothing at all — there is no field-level fallback between templates. Composition happens only inside the winning template, across its composed_of component templates and its own template block. Anything you need must live under the winner.
  • Why does Elasticsearch reject two overlapping templates with equal priority instead of picking one?
    Because the choice would be arbitrary and invisible. Failing the PUT surfaces the ambiguity to the person deploying the template, in a request that errors immediately, rather than letting it surface weeks later as an index created with unexpected settings that nobody can attribute to a template.

saying these in an interview costs you the question

  • Says all matching index templates are merged together
  • Assumes the most specific pattern automatically wins
  • Thinks a tie is broken by name, age or insertion order
  • Ignores Elastic's built-in templates when choosing a priority
  • Registers a catch-all * template at high priority

context

resolving links…