OpenSearch/docs/reference/indices/templates.asciidoc

252 lines
6.4 KiB
Plaintext
Raw Normal View History

[[indices-templates]]
=== Put index template API
++++
<titleabbrev>Put index template</titleabbrev>
++++
Creates or updates an index template.
[source,console]
--------------------------------------------------
PUT _template/template_1
{
"index_patterns": ["te*", "bar*"],
"settings": {
"number_of_shards": 1
},
"mappings": {
Update the default for include_type_name to false. (#37285) * Default include_type_name to false for get and put mappings. * Default include_type_name to false for get field mappings. * Add a constant for the default include_type_name value. * Default include_type_name to false for get and put index templates. * Default include_type_name to false for create index. * Update create index calls in REST documentation to use include_type_name=true. * Some minor clean-ups around the get index API. * In REST tests, use include_type_name=true by default for index creation. * Make sure to use 'expression == false'. * Clarify the different IndexTemplateMetaData toXContent methods. * Fix FullClusterRestartIT#testSnapshotRestore. * Fix the ml_anomalies_default_mappings test. * Fix GetFieldMappingsResponseTests and GetIndexTemplateResponseTests. We make sure to specify include_type_name=true during xContent parsing, so we continue to test the legacy typed responses. XContent generation for the typeless responses is currently only covered by REST tests, but we will be adding unit test coverage for these as we implement each typeless API in the Java HLRC. This commit also refactors GetMappingsResponse to follow the same appraoch as the other mappings-related responses, where we read include_type_name out of the xContent params, instead of creating a second toXContent method. This gives better consistency in the response parsing code. * Fix more REST tests. * Improve some wording in the create index documentation. * Add a note about types removal in the create index docs. * Fix SmokeTestMonitoringWithSecurityIT#testHTTPExporterWithSSL. * Make sure to mention include_type_name in the REST docs for affected APIs. * Make sure to use 'expression == false' in FullClusterRestartIT. * Mention include_type_name in the REST templates docs.
2019-01-14 16:08:01 -05:00
"_source": {
"enabled": false
},
"properties": {
"host_name": {
"type": "keyword"
},
Update the default for include_type_name to false. (#37285) * Default include_type_name to false for get and put mappings. * Default include_type_name to false for get field mappings. * Add a constant for the default include_type_name value. * Default include_type_name to false for get and put index templates. * Default include_type_name to false for create index. * Update create index calls in REST documentation to use include_type_name=true. * Some minor clean-ups around the get index API. * In REST tests, use include_type_name=true by default for index creation. * Make sure to use 'expression == false'. * Clarify the different IndexTemplateMetaData toXContent methods. * Fix FullClusterRestartIT#testSnapshotRestore. * Fix the ml_anomalies_default_mappings test. * Fix GetFieldMappingsResponseTests and GetIndexTemplateResponseTests. We make sure to specify include_type_name=true during xContent parsing, so we continue to test the legacy typed responses. XContent generation for the typeless responses is currently only covered by REST tests, but we will be adding unit test coverage for these as we implement each typeless API in the Java HLRC. This commit also refactors GetMappingsResponse to follow the same appraoch as the other mappings-related responses, where we read include_type_name out of the xContent params, instead of creating a second toXContent method. This gives better consistency in the response parsing code. * Fix more REST tests. * Improve some wording in the create index documentation. * Add a note about types removal in the create index docs. * Fix SmokeTestMonitoringWithSecurityIT#testHTTPExporterWithSSL. * Make sure to mention include_type_name in the REST docs for affected APIs. * Make sure to use 'expression == false' in FullClusterRestartIT. * Mention include_type_name in the REST templates docs.
2019-01-14 16:08:01 -05:00
"created_at": {
"type": "date",
"format": "EEE MMM dd HH:mm:ss Z yyyy"
}
}
}
}
--------------------------------------------------
// TESTSETUP
[[put-index-template-api-request]]
==== {api-request-title}
`PUT /_template/<index-template>`
[[put-index-template-api-desc]]
==== {api-description-title}
Use the PUT index template API
to create or update an index template.
// tag::index-template-def[]
Index templates define <<index-modules-settings,settings>> and <<mapping,mappings>>
that you can automatically apply when creating new indices.
{es} applies templates to new indices
based on an index pattern that matches the index name.
// end::index-template-def[]
Index templates are only applied during index creation.
Changes to index templates do not affect existing indices.
Settings and mappings specified in <<indices-create-index, create index>> API requests
override any settings or mappings specified in an index template.
===== Comments in index templates
You can use C-style /* */ block comments in index templates.
You can includes comments anywhere in the request body,
except before the opening curly bracket.
[[getting]]
===== Getting templates
See <<indices-get-template>>.
[[put-index-template-api-path-params]]
==== {api-path-parms-title}
`<index-template>`::
(Required, string)
Name of the index template to create.
[[put-index-template-api-query-params]]
==== {api-query-parms-title}
`create`::
(Optional, boolean)
If `true`, this request cannot replace or update existing index templates.
Defaults to `false`.
include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
`order`::
(Optional,integer)
Order in which {es} applies this template
if index matches multiple templates.
+
Templates with lower `order` values are merged first.
Templates with higher `order` values are merged later,
overriding templates with lower values.
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
[[put-index-template-api-request-body]]
==== {api-request-body-title}
`index_patterns`::
(Required, array of strings)
Array of wildcard expressions
used to match the names of indices during creation.
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 index templates externally.
This number is not automatically generated by {es}.
[[put-index-template-api-example]]
==== {api-examples-title}
===== Index template with index aliases
You can include <<indices-aliases,index aliases>> in an index template.
[source,console]
--------------------------------------------------
PUT _template/template_1
{
"index_patterns" : ["te*"],
"settings" : {
"number_of_shards" : 1
},
"aliases" : {
"alias1" : {},
"alias2" : {
"filter" : {
"term" : {"user" : "kimchy" }
},
"routing" : "kimchy"
},
"{index}-alias" : {} <1>
}
}
--------------------------------------------------
// TEST[s/^/DELETE _template\/template_1\n/]
<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.
[[multiple-templates]]
===== Indices matching multiple templates
Multiple index templates can potentially match an index, in this case,
both the settings and mappings are merged into the final configuration
of the index. The order of the merging can be controlled using the
`order` parameter, with lower order being applied first, and higher
orders overriding them. For example:
[source,console]
--------------------------------------------------
PUT /_template/template_1
{
"index_patterns" : ["*"],
"order" : 0,
"settings" : {
"number_of_shards" : 1
},
"mappings" : {
Update the default for include_type_name to false. (#37285) * Default include_type_name to false for get and put mappings. * Default include_type_name to false for get field mappings. * Add a constant for the default include_type_name value. * Default include_type_name to false for get and put index templates. * Default include_type_name to false for create index. * Update create index calls in REST documentation to use include_type_name=true. * Some minor clean-ups around the get index API. * In REST tests, use include_type_name=true by default for index creation. * Make sure to use 'expression == false'. * Clarify the different IndexTemplateMetaData toXContent methods. * Fix FullClusterRestartIT#testSnapshotRestore. * Fix the ml_anomalies_default_mappings test. * Fix GetFieldMappingsResponseTests and GetIndexTemplateResponseTests. We make sure to specify include_type_name=true during xContent parsing, so we continue to test the legacy typed responses. XContent generation for the typeless responses is currently only covered by REST tests, but we will be adding unit test coverage for these as we implement each typeless API in the Java HLRC. This commit also refactors GetMappingsResponse to follow the same appraoch as the other mappings-related responses, where we read include_type_name out of the xContent params, instead of creating a second toXContent method. This gives better consistency in the response parsing code. * Fix more REST tests. * Improve some wording in the create index documentation. * Add a note about types removal in the create index docs. * Fix SmokeTestMonitoringWithSecurityIT#testHTTPExporterWithSSL. * Make sure to mention include_type_name in the REST docs for affected APIs. * Make sure to use 'expression == false' in FullClusterRestartIT. * Mention include_type_name in the REST templates docs.
2019-01-14 16:08:01 -05:00
"_source" : { "enabled" : false }
}
}
PUT /_template/template_2
{
"index_patterns" : ["te*"],
"order" : 1,
"settings" : {
"number_of_shards" : 1
},
"mappings" : {
Update the default for include_type_name to false. (#37285) * Default include_type_name to false for get and put mappings. * Default include_type_name to false for get field mappings. * Add a constant for the default include_type_name value. * Default include_type_name to false for get and put index templates. * Default include_type_name to false for create index. * Update create index calls in REST documentation to use include_type_name=true. * Some minor clean-ups around the get index API. * In REST tests, use include_type_name=true by default for index creation. * Make sure to use 'expression == false'. * Clarify the different IndexTemplateMetaData toXContent methods. * Fix FullClusterRestartIT#testSnapshotRestore. * Fix the ml_anomalies_default_mappings test. * Fix GetFieldMappingsResponseTests and GetIndexTemplateResponseTests. We make sure to specify include_type_name=true during xContent parsing, so we continue to test the legacy typed responses. XContent generation for the typeless responses is currently only covered by REST tests, but we will be adding unit test coverage for these as we implement each typeless API in the Java HLRC. This commit also refactors GetMappingsResponse to follow the same appraoch as the other mappings-related responses, where we read include_type_name out of the xContent params, instead of creating a second toXContent method. This gives better consistency in the response parsing code. * Fix more REST tests. * Improve some wording in the create index documentation. * Add a note about types removal in the create index docs. * Fix SmokeTestMonitoringWithSecurityIT#testHTTPExporterWithSSL. * Make sure to mention include_type_name in the REST docs for affected APIs. * Make sure to use 'expression == false' in FullClusterRestartIT. * Mention include_type_name in the REST templates docs.
2019-01-14 16:08:01 -05:00
"_source" : { "enabled" : true }
}
}
--------------------------------------------------
// TEST[s/^/DELETE _template\/template_1\n/]
The above will disable storing the `_source`, but
for indices that start with `te*`, `_source` will still be enabled.
Note, for mappings, the merging is "deep", meaning that specific
object/property based mappings can easily be added/overridden on higher
order templates, with lower order templates providing the basis.
NOTE: Multiple matching templates with the same order value will
result in a non-deterministic merging order.
[[versioning-templates]]
===== Template versioning
You can use the `version` parameter
to add an optional version number to an index 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 /_template/template_1
{
"index_patterns" : ["*"],
"order" : 0,
"settings" : {
"number_of_shards" : 1
},
"version": 123
}
--------------------------------------------------
To check the `version`,
you can use the <<indices-get-template, get index template>> API
with the <<common-options-response-filtering, `filter_path`>> query parameter
to return only the version number:
[source,console]
--------------------------------------------------
GET /_template/template_1?filter_path=*.version
--------------------------------------------------
// TEST[continued]
The API returns the following response:
[source,js]
--------------------------------------------------
{
"template_1" : {
"version" : 123
}
}
--------------------------------------------------
// TESTRESPONSE