Index & Component Templates

## The problem templates solve Most real Elasticsearch deployments do not have one index; they have a *family* of indices with the same shape — `logs-app-2024.06.01`, `logs-app-2024.06.02`, or one index per tenant, or one per daily snapshot of a catalogue. Every one of those indices needs the same number of shards, the same analyzers, the same explicit mapping and often the same alias. Passing all of that on every create call is unworkable: indices are frequently created implicitly by an indexing request or by a rollover, where no human is present to supply a body. An **index template** is the stored answer. It says: *any index whose name matches these patterns should be born with this configuration*. ## Anatomy A composable index template is stored at `PUT _index_template/<name>` and has these parts: - `index_patterns` — one or more name patterns, e.g. `["logs-app-*"]`. Matching is against the **whole** index name, so `logs-*` does not match `app-logs-1`. - `template` — the payload, containing any of `settings` (shards, replicas, refresh interval, analysis definitions), `mappings` (field types, dynamic settings, dynamic templates) and `aliases`. - `composed_of` — an ordered list of **component template** names whose contents are merged in before the `template` block. Component templates are stored separately with `PUT _component_template/<name>` and are the reuse mechanism: a shared "base settings" component and a shared "common fields" component can be referenced by twenty index templates. - `priority` — a number used to pick a single winner when several templates match a name. - `version` and `_meta` — free-form bookkeeping fields Elasticsearch stores but does not interpret; useful for recording who owns the template and which revision is deployed. A template may also declare a `data_stream` section, which makes matching names create data streams rather than plain indices; the data-stream mechanics themselves are a separate topic. ## When it is applied — and only then Elasticsearch evaluates templates at exactly one moment: when an index is created. That creation can be explicit (`PUT /logs-app-000001`), implicit (indexing a document into a name that does not exist, if auto-create is allowed), or the result of a rollover. At that moment the engine finds the matching template, composes it, merges anything supplied in the create-index request itself on top, and writes the resulting settings, mappings and aliases into the cluster state as that index's metadata. Afterwards, the index and the template are **completely independent objects**. The index does not hold a reference to the template. Nothing re-reads the template later. This is the single most common misunderstanding in interviews, and the source of a whole class of production surprises: - You fix a field from `text` to `keyword` in the template — yesterday's index still has `text` and still fails your `terms` aggregation. - You raise `number_of_replicas` in the template — existing indices keep the old value until you change them with `PUT /<index>/_settings`. - You delete the template — every index created from it carries on unchanged. ## What a template cannot do Templates cannot perform an operation Elasticsearch does not otherwise support. Field types are immutable once an index exists, so no amount of template editing changes an existing field's type; the fix is to reindex into a fresh index (usually behind an alias so readers do not notice the swap) or, for a rolling family, to roll over and let only new data get the corrected mapping. Templates also do not validate the data you send; they only shape the index. Some settings *are* dynamically updatable on a live index (`number_of_replicas`, `refresh_interval`), so for those the template edit plus an explicit settings update on existing indices gets you a fully consistent fleet. Static settings such as `number_of_shards` can never be changed on an existing index. ## Practical consequences Because the template is only ever a birth certificate, treat it as configuration-as-code: keep the JSON in version control, apply it from CI, and give it a `version` and `_meta` so you can tell which revision an environment has. Verify that a change actually resolves the way you expect *before* the next index is born, using the simulate API, because a template mistake is only visible once the wrong index already exists, and by then correcting it costs a reindex. Finally, remember the interaction with dynamic mapping. If no template matches a new index name, the index is created with cluster defaults and Elasticsearch guesses field types from the first document it sees. A missing or mistyped `index_patterns` therefore does not fail loudly — it silently falls back to guessing, which is why a field that "used to be a keyword" suddenly shows up as `text` with a `.keyword` sub-field.