-
Notifications
You must be signed in to change notification settings - Fork 25k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
Backports the following commits to 7.x: - Initial documentation for index templates V2 (#55755)
- Loading branch information
Showing
7 changed files
with
725 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,272 @@ | ||
| [[indices-component-template]] | ||
| === Component template API | ||
| ++++ | ||
| <titleabbrev>Component template</titleabbrev> | ||
| ++++ | ||
|
|
||
| Component templates are building blocks that specify mappings, settings, or alias configuration, but | ||
| don't apply to a set of indices themselves. To be used a component template must be specified in the | ||
| `composed_of` of an <<indices-templates,index template>>. | ||
|
|
||
| [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-desc]] | ||
| ==== {api-description-title} | ||
|
|
||
| Use the PUT component template API to create or update a component template. | ||
|
|
||
| // tag::component-template-def[] | ||
| Component templates define <<index-modules-settings,settings>>, <<mapping,mappings>>, and | ||
| <<indices-aliases,aliases>> that you can automatically apply when creating new indices. On their own | ||
| component templates are not matched or applied to an index, instead they are used in the | ||
| `composed_of` definition of an <<indices-templates,index template>> to make up the final index | ||
| configuration. | ||
| // end::component-template-def[] | ||
|
|
||
| Component templates are only used during index creation. Changes to component templates do not | ||
| affect existing indices. Settings and mappings specified in <<indices-create-index, create index>> | ||
| API requests and <<indices-templates,index templates>> override any settings or mappings specified | ||
| in a component template. | ||
|
|
||
| ===== 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. | ||
|
|
||
| [[getting-component-templates]] | ||
| ===== Getting component templates | ||
|
|
||
| === Get component template API | ||
| ++++ | ||
| <titleabbrev>Get component template</titleabbrev> | ||
| ++++ | ||
|
|
||
| Returns information about one or more component templates. | ||
|
|
||
| [source,console] | ||
| -------------------------------------------------- | ||
| GET /_component_template/template_1 | ||
| -------------------------------------------------- | ||
|
|
||
| [[get-component-template-api-request]] | ||
| ==== {api-request-title} | ||
|
|
||
| `GET /_component-template/<component-template>` | ||
|
|
||
|
|
||
| [[get-component-template-api-path-params]] | ||
| ==== {api-path-parms-title} | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=index-template] | ||
| + | ||
| To return all component templates, omit this parameter or use a value of `*`. | ||
|
|
||
|
|
||
| [[get-component-template-api-query-params]] | ||
| ==== {api-query-parms-title} | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings] | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=local] | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] | ||
|
|
||
|
|
||
| [[get-component-template-api-example]] | ||
| ==== {api-examples-title} | ||
|
|
||
|
|
||
| [[get-component-template-api-wildcard-ex]] | ||
| ===== Get component templates using a wildcard expression | ||
|
|
||
| [source,console] | ||
| -------------------------------------------------- | ||
| GET /_component_template/temp* | ||
| -------------------------------------------------- | ||
|
|
||
|
|
||
| [[get-component-template-api-all-ex]] | ||
| ===== Get all component templates | ||
|
|
||
| [source,console] | ||
| -------------------------------------------------- | ||
| GET /_component_template | ||
| -------------------------------------------------- | ||
|
|
||
| [[put-component-template-api-path-params]] | ||
| ==== {api-path-parms-title} | ||
|
|
||
| `<component-template>`:: | ||
| (Required, string) | ||
| Name of the component template to create. | ||
|
|
||
|
|
||
| [[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::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] | ||
|
|
||
| [[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. | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases] | ||
|
|
||
| include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings] | ||
|
|
||
| include::{docdir}/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}. | ||
|
|
||
| `_meta`:: | ||
| (Optional, object) | ||
| Optional user metadata about the component template. May have any contents. | ||
| This map is not automatically generated by {es}. | ||
|
|
||
| [[put-component-template-api-example]] | ||
| ==== {api-examples-title} | ||
|
|
||
| ===== Component template with index aliases | ||
|
|
||
| You can include <<indices-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" : "kimchy" } | ||
| }, | ||
| "routing" : "kimchy" | ||
| }, | ||
| "{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 | ||
|
|
||
| Component templates on their own don't apply or interact with indices at all. In order for them to | ||
| be effective, they must be used as part of index template's `composed_of` field to take effect. See | ||
| the <<indices-templates,index templates>> documentation for more information. | ||
|
|
||
| [[component-templates-version]] | ||
| ===== Component template versioning | ||
|
|
||
| You can use the `version` parameter to add an optional version number to a component template. External | ||
| systems can use these version numbers to simplify template management. | ||
|
|
||
| The `version` parameter is completely optional and not automatically generated 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 optional metadata to a component template. This is a | ||
| user-defined map that can contain any data. This data will be stored in the cluster state however, | ||
| so keeping it short is preferrable. | ||
|
|
||
| The `_meta` parameter is completely optional and not automatically generated 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.