-
Notifications
You must be signed in to change notification settings - Fork 113
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
base: main
Are you sure you want to change the base?
Conversation
🔍 Preview links for changed docs |
There was a problem hiding this 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. |
There was a problem hiding this comment.
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:
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
* 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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
* 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. |
There was a problem hiding this comment.
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.
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. |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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.
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: |
This attempts to improve the Templates docs by:
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