mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
33a71e3289
* Remove `es-test-dir` book-scoped variable * Remove `plugins-examples-dir` book-scoped variable * Remove `:dependencies-dir:` and `:xes-repo-dir:` book-scoped variables - In `index.asciidoc`, two variables (`:dependencies-dir:` and `:xes-repo-dir:`) were removed. - In `sql/index.asciidoc`, the `:sql-tests:` path was updated to fuller path - In `esql/index.asciidoc`, the `:esql-tests:` path was updated idem * Replace `es-repo-dir` with `es-ref-dir` * Move `:include-xpack: true` to few files that use it, remove from index.asciidoc
270 lines
8.4 KiB
Text
270 lines
8.4 KiB
Text
[[indices-component-template]]
|
|
=== Create or update component template API
|
|
++++
|
|
<titleabbrev>Create or update component template</titleabbrev>
|
|
++++
|
|
|
|
Creates or updates a component template. Component templates are building blocks
|
|
for constructing <<index-templates,index templates>> that specify index
|
|
<<mapping,mappings>>, <<index-modules-settings,settings>>, and
|
|
<<aliases,aliases>>.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _component_template/template_1
|
|
{
|
|
"template": {
|
|
"settings": {
|
|
"number_of_shards": 1
|
|
},
|
|
"mappings": {
|
|
"_source": {
|
|
"enabled": false
|
|
},
|
|
"properties": {
|
|
"host_name": {
|
|
"type": "keyword"
|
|
},
|
|
"created_at": {
|
|
"type": "date",
|
|
"format": "EEE MMM dd HH:mm:ss Z yyyy"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE _component_template/template_*
|
|
--------------------------------------------------
|
|
// TEARDOWN
|
|
|
|
//////////////////////////
|
|
|
|
[[put-component-template-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_component_template/<component-template>`
|
|
|
|
[[put-component-template-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the
|
|
`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
|
|
privilege>> to use this API.
|
|
|
|
[[put-component-template-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
An index template can be composed of multiple component templates.
|
|
To use a component template, specify it in an index template's `composed_of` list.
|
|
Component templates are only applied to new data streams and indices
|
|
as part of a matching index template.
|
|
|
|
Settings and mappings specified directly in the index template or the <<indices-create-index, create index>>
|
|
request override any settings or mappings specified in a component template.
|
|
|
|
Component templates are only used during index creation. For data streams, this
|
|
includes data stream creation and the creation of a stream's backing indices.
|
|
Changes to component templates do not
|
|
affect existing indices, including a stream's backing indices.
|
|
|
|
===== Comments in component templates
|
|
You can use C-style /* */ block comments in component templates.
|
|
You can include comments anywhere in the request body,
|
|
except before the opening curly bracket.
|
|
|
|
[[put-component-template-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<component-template>`::
|
|
(Required, string)
|
|
Name of the component template to create.
|
|
+
|
|
[IMPORTANT]
|
|
====
|
|
{es} includes the following built-in component templates:
|
|
|
|
// tag::built-in-component-templates[]
|
|
- `logs@mappings`
|
|
- `logs@settings`
|
|
- `metrics@mappings`
|
|
- `metrics@settings`
|
|
- `metrics@tsdb-settings`
|
|
- `synthetics@mapping`
|
|
- `synthetics@settings`
|
|
// end::built-in-component-templates[]
|
|
|
|
{fleet-guide}/fleet-overview.html[{agent}] uses these templates to configure
|
|
backing indices for its data streams.
|
|
If you want to customize these templates, don't override them as they may be reset after an update.
|
|
Instead, look for a `*@custom` component template in the `composed_of` section of the managed index template.
|
|
These custom component templates allow you to customize the mappings of managed index templates,
|
|
without having to override managed index templates or component templates.
|
|
Note that the custom component templates may not exist yet.
|
|
After you create them using the <<indices-component-template>>, they'll be picked up by the index template.
|
|
See <<data-streams-change-mappings-and-settings>> on how to apply the changes to the corresponding data stream.
|
|
|
|
To avoid naming collisions with built-in and Fleet-managed component templates,
|
|
avoid using `@` as part of your own component template names.
|
|
The exception of that rule are the `*@custom` component templates that let you safely customize managed index templates.
|
|
====
|
|
|
|
[[put-component-template-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`create`::
|
|
(Optional, Boolean)
|
|
If `true`, this request cannot replace or update existing component templates.
|
|
Defaults to `false`.
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
[role="child_attributes"]
|
|
[[put-component-template-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`template`::
|
|
(Required, object)
|
|
This is the template to be applied, may optionally include a `mappings`,
|
|
`settings`, or `aliases` configuration.
|
|
+
|
|
.Properties of `template`
|
|
[%collapsible%open]
|
|
====
|
|
`aliases`::
|
|
(Optional, object of objects) Aliases to add.
|
|
+
|
|
include::{es-ref-dir}/indices/put-index-template.asciidoc[tag=template-ds-alias]
|
|
+
|
|
include::{es-ref-dir}/indices/create-index.asciidoc[tag=aliases-props]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
|
|
====
|
|
|
|
`version`::
|
|
(Optional, integer)
|
|
Version number used to manage component templates externally.
|
|
This number is not automatically generated or incremented by {es}.
|
|
|
|
`allow_auto_create`::
|
|
(Optional, Boolean)
|
|
This setting overrides the value of the
|
|
<<index-creation,`action.auto_create_index`>> cluster setting. If set to
|
|
`true` in a template, then indices can be automatically created using that
|
|
template even if auto-creation of indices is disabled via
|
|
`actions.auto_create_index`. If set to `false`, then indices or data streams matching the
|
|
template must always be explicitly created, and may never be automatically
|
|
created.
|
|
|
|
`_meta`::
|
|
(Optional, object)
|
|
Optional user metadata about the component template. May have any contents.
|
|
This map is not automatically generated by {es}.
|
|
|
|
`deprecated`::
|
|
(Optional, boolean)
|
|
Marks this component template as deprecated.
|
|
When a deprecated component template is referenced when creating or updating a non-deprecated index template,
|
|
{es} will emit a deprecation warning.
|
|
|
|
[[put-component-template-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
===== Component template with index aliases
|
|
|
|
You can include <<aliases,index aliases>> in a component template.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _component_template/template_1
|
|
{
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
},
|
|
"aliases" : {
|
|
"alias1" : {},
|
|
"alias2" : {
|
|
"filter" : {
|
|
"term" : {"user.id" : "kimchy" }
|
|
},
|
|
"routing" : "shard-1"
|
|
},
|
|
"{index}-alias" : {} <1>
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
<1> the `{index}` placeholder in the alias name will be replaced with the
|
|
actual index name that the template gets applied to, during index creation.
|
|
|
|
[[applying-component-templates]]
|
|
===== Applying component templates
|
|
|
|
You cannot directly apply a component template to a data stream or index.
|
|
To be applied, a component template must be included in an index template's `composed_of` list. See <<index-templates>>.
|
|
|
|
[[component-templates-version]]
|
|
===== Component template versioning
|
|
|
|
You can use the `version` parameter to add a version number to a component template.
|
|
External systems can use these version numbers to simplify template management.
|
|
|
|
The `version` parameter is optional and not automatically generated or used by {es}.
|
|
|
|
To unset a `version`, replace the template without specifying one.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_component_template/template_1
|
|
{
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
}
|
|
},
|
|
"version": 123
|
|
}
|
|
--------------------------------------------------
|
|
|
|
To check the `version`, you can use the <<getting-component-templates,get component template API>>.
|
|
|
|
[[component-templates-metadata]]
|
|
===== Component template metadata
|
|
|
|
You can use the `_meta` parameter to add arbitrary metadata to a component template.
|
|
This user-defined object is stored in the cluster state,
|
|
so keeping it short is preferable.
|
|
|
|
The `_meta` parameter is optional and not automatically generated or used by {es}.
|
|
|
|
To unset `_meta`, replace the template without specifying one.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_component_template/template_1
|
|
{
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
}
|
|
},
|
|
"_meta": {
|
|
"description": "set number of shards to one",
|
|
"serialization": {
|
|
"class": "MyComponentTemplate",
|
|
"id": 10
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
To check the `_meta`, you can use the <<getting-component-templates,get component template>> API.
|