Skip to content

Fix up the 'Templates' section #2178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

kilfoyle
Copy link
Contributor

@kilfoyle kilfoyle commented Jul 18, 2025

This attempts to improve the Templates docs by:

  • Adding more explanation into the page rather than just linking to the API docs.
  • Removing the "manage index templates" content that is duplicated; this section in the more prominent "Index basics" will be the single source of truth.
  • Improving the narrative by making a clearer distinction between "Index templates" and "component templates", with separate sections for each.
  • Changing the giant warning about index pattern collisions (which takes about 1/3 of the page) into a subsection of "Index templates"; this should flow better and be less jarring for readers.
  • Including the API instructions for creating each kind of template, and also link to the Kibana version of those steps that are included in the Index basics page.
  • Adding a tip with links to the subpages about simulating an index template and about ignore missing component templates, just to help people be aware of these cool features.

Please see preview page: Templates

@eedugon This was prompted by your suggestions here so I hope you don't mind my adding you as a reviewer. 🙏

Closes: #2056

Copy link

github-actions bot commented Jul 18, 2025

Copy link
Contributor

@eedugon eedugon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! I've added some suggestions for the explanations and descriptions around component templates and index templates.

btw, I've also found this insteresting blog that I'm not sure if it could make sense to link also: https://www.elastic.co/search-labs/blog/index-composable-templates

In this doc we also mention legacy templates but we don't give any context or link..... so I don't know how best to address this. I don't even know if we have the old legacy templates behavior documented (this is an old doc about legacy templates).

::::{note}
This topic describes the composable index templates introduced in {{es}} 7.8. For information about how index templates worked previously, see the [legacy template documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-template).
::::
Templates are tools used to construct indices in {{es}}. They specify the properties that each created index will have.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel the word tools a bit vague in this context, and I'd like to treat templates in singular, as the mechanism. Let me know your thoughts about this proposal:

Suggested change
Templates are tools used to construct indices in {{es}}. They specify the properties that each created index will have.
Templates are the mechanism that {{es}} uses to apply settings, mappings, and other configurations when creating indices or data streams.

(I like including also data streams, as the way to create data streams is also through templates).

Another possibility:

Templates are the mechanism by which {{es}} applies settings, mappings, and other configurations when creating indices or data streams.


You configure templates prior to creating indices. This way, when each index is created, either manually or through the indexing of a document, the template settings are used as a basis for creating the index. When used with a [data stream](/manage-data/data-store/data-streams.md), a template configures the stream's backing indices as they are created.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You configure templates prior to creating indices. This way, when each index is created, either manually or through the indexing of a document, the template settings are used as a basis for creating the index. When used with a [data stream](/manage-data/data-store/data-streams.md), a template configures the stream's backing indices as they are created.
You configure templates prior to creating indices or data streams. When an index is created, either manually or by indexing a document, the matching template determines the settings, mappings, and other configurations to apply. When used with a [data stream](/manage-data/data-store/data-streams.md), a template also defines how each backing index is configured as it is created.


There are two types of templates: index templates and [component templates](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-component-template). Component templates are reusable building blocks that configure mappings, settings, and aliases. While you can use component templates to construct index templates, they aren’t directly applied to a set of indices. Index templates can contain a collection of component templates, as well as directly specify settings, mappings, and aliases.
* An [**index template**](#index-templates) is used to configure indices when they are created, by specifying the mappings, settings, and aliases that each index inherits.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* An [**index template**](#index-templates) is used to configure indices when they are created, by specifying the mappings, settings, and aliases that each index inherits.
* An [**index template**](#index-templates) is the main configuration object applied when creating an index or data stream. It matches index names using `index_patterns` and resolves conflicts using a `priority` value. An index template can optionally define settings, mappings, and aliases directly, and refer to a list of component templates that provide reusable configuration blocks. It can also indicate whether it should create a data stream or a regular index.

Not sure.... maybe too long, but in the intro to index templates I think there's something important to highlight:

  • is the component that has to match the index or data stream name
  • it's used to determine if the item to create is a regular index or a data stream (for this we can just link to data streams documentation).
  • can optionally include settings, mappings, and aliases, and refer to component templates.

The current description just puts the focus on mappings, settings and aliases, which is more aligned with the legacy templates and old way of working, without using composable templates.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe you prefer something much shorter here and describe the points I mention later in the section dedicated to index templates. Whatever you prefer :)


The following conditions apply to index templates:
* A [**component template**](#component-templates) is a reusable building block used to construct index templates.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* A [**component template**](#component-templates) is a reusable building block used to construct index templates.
* A [**component template**](#component-templates) is a reusable building block that defines settings, mappings, and aliases. Component templates are not applied directly; they must be referenced by index templates.


A **component template** is a reusable building block, containing mappings, settings, and aliases, used to construct an index template. Component templates are used only to construct index templates and are not applied to indices directly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Used to construct index templates sound a bit weird when we want to mean that index templates include component templates to reuse their contents.

Suggested change
A **component template** is a reusable building block, containing mappings, settings, and aliases, used to construct an index template. Component templates are used only to construct index templates and are not applied to indices directly.
A **component template** is a reusable building block that defines mappings, settings, and aliases. Component templates are not applied directly to indices, but referenced by index templates and used when determining the final configuration of an index.

* Composable templates take precedence over legacy templates. If no composable template matches a given index, a legacy template may still match and be applied.
The following conditions apply to using templates:

* Composable index templates take precedence over legacy templates. If no composable template matches a given index, a legacy template may still match and be applied.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a link in legacy templates? The concept of legacy templates doesn't appear in the doc, and might be difficult for a reader to understand what's about.


* Composable templates take precedence over legacy templates. If no composable template matches a given index, a legacy template may still match and be applied.
The following conditions apply to using templates:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding one sentence that can be the glue for what's coming next.

Suggested change
The following conditions apply to using templates:
Together, index templates and their referenced component templates form what is known as *composable templates*.
The following conditions apply to using templates:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Improvements to "Templates" section
2 participants