* [DOCS] Add simulate ref pages * Add links & experimental tags * Fixed simulate index response * Apply suggestions from code review Co-authored-by: James Rodewig <james.rodewig@elastic.co> *Incorporate review feedback.
This commit is contained in:
debadair
GitHub
parent
dc9e364ff2
commit
b769e9143d
|
|
@ -58,11 +58,8 @@ index settings, aliases, mappings, and index templates.
|
||||||
* <<indices-component-template>>
|
* <<indices-component-template>>
|
||||||
* <<getting-component-templates>>
|
* <<getting-component-templates>>
|
||||||
* <<indices-template-exists>>
|
* <<indices-template-exists>>
|
||||||
|
* <<indices-simulate-index>>
|
||||||
[float]
|
* <<indices-simulate-template>>
|
||||||
[[component-template-apis]]
|
|
||||||
=== Component templates:
|
|
||||||
* <<indices-component-template>>
|
|
||||||
|
|
||||||
[float]
|
[float]
|
||||||
[[monitoring]]
|
[[monitoring]]
|
||||||
|
|
@ -148,6 +145,10 @@ include::indices/rollover-index.asciidoc[]
|
||||||
|
|
||||||
include::indices/shrink-index.asciidoc[]
|
include::indices/shrink-index.asciidoc[]
|
||||||
|
|
||||||
|
include::indices/simulate-index.asciidoc[]
|
||||||
|
|
||||||
|
include::indices/simulate-template.asciidoc[]
|
||||||
|
|
||||||
include::indices/split-index.asciidoc[]
|
include::indices/split-index.asciidoc[]
|
||||||
|
|
||||||
include::indices/synced-flush.asciidoc[]
|
include::indices/synced-flush.asciidoc[]
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,176 @@
|
||||||
|
[[indices-simulate-index]]
|
||||||
|
=== Simulate index API
|
||||||
|
++++
|
||||||
|
<titleabbrev>Simulate index</titleabbrev>
|
||||||
|
++++
|
||||||
|
|
||||||
|
experimental[]
|
||||||
|
|
||||||
|
Returns the index configuration that would be applied to the specified index from an
|
||||||
|
existing <<indices-templates, index template>>.
|
||||||
|
|
||||||
|
////
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
PUT _index_template/template_1
|
||||||
|
{
|
||||||
|
"index_patterns": ["myindex*"],
|
||||||
|
"template": {
|
||||||
|
"settings": {
|
||||||
|
"number_of_shards": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// TESTSETUP
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
DELETE _index_template/*
|
||||||
|
--------------------------------------------------
|
||||||
|
// TEARDOWN
|
||||||
|
////
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
POST /_index_template/_simulate_index/myindex-1
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
[[simulate-index-api-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`POST /_index_template/_simulate_index/<index>`
|
||||||
|
|
||||||
|
|
||||||
|
[[simulate-index-api-path-params]]
|
||||||
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
|
`<index>`::
|
||||||
|
(Required, string)
|
||||||
|
Name of the index to simulate.
|
||||||
|
|
||||||
|
[[simulate-index-api-query-params]]
|
||||||
|
==== {api-query-parms-title}
|
||||||
|
////
|
||||||
|
`cause`::
|
||||||
|
(Optional, string) The reason for running the simulation.
|
||||||
|
////
|
||||||
|
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
||||||
|
|
||||||
|
[role="child_attributes"]
|
||||||
|
[[simulate-index-api-response-body]]
|
||||||
|
==== {api-response-body-title}
|
||||||
|
|
||||||
|
`overlapping`::
|
||||||
|
(array) Any templates that also matched the index but were superseded by a higher-priority template.
|
||||||
|
Response includes an empty array if there are no overlapping templates.
|
||||||
|
+
|
||||||
|
.Properties of `overlapping`
|
||||||
|
[%collapsible%open]
|
||||||
|
====
|
||||||
|
`name`::
|
||||||
|
(string) Name of the superseded template.
|
||||||
|
|
||||||
|
`index_patterns`::
|
||||||
|
(array) Index patterns that the superseded template applies to.
|
||||||
|
====
|
||||||
|
|
||||||
|
`template`::
|
||||||
|
(object)
|
||||||
|
The settings, mappings, and aliases that would be applied to the index.
|
||||||
|
+
|
||||||
|
.Properties of `template`
|
||||||
|
[%collapsible%open]
|
||||||
|
====
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases]
|
||||||
|
+
|
||||||
|
Response includes an empty object if no aliases would be applied.
|
||||||
|
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]
|
||||||
|
+
|
||||||
|
Omitted from the response if no mappings would be applied.
|
||||||
|
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
|
||||||
|
+
|
||||||
|
Response includes an empty object if no settings would be applied.
|
||||||
|
====
|
||||||
|
|
||||||
|
[[simulate-index-api-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
The following example shows the configuration that would be applied to `myindex-1` by
|
||||||
|
an existing template.
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
PUT /_component_template/ct1 <1>
|
||||||
|
{
|
||||||
|
"template": {
|
||||||
|
"settings": {
|
||||||
|
"index.number_of_shards": 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT /_component_template/ct2 <2>
|
||||||
|
{
|
||||||
|
"template": {
|
||||||
|
"settings": {
|
||||||
|
"index.number_of_replicas": 0
|
||||||
|
},
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"@timestamp": {
|
||||||
|
"type": "date"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT /_index_template/final-template <3>
|
||||||
|
{
|
||||||
|
"index_patterns": ["myindex*"],
|
||||||
|
"composed_of": ["ct1", "ct2"],
|
||||||
|
"priority": 5
|
||||||
|
}
|
||||||
|
|
||||||
|
POST /_index_template/_simulate_index/myindex-1 <4>
|
||||||
|
--------------------------------------------------
|
||||||
|
<1> Create a component template (`ct1`) that sets the number of shards to 2
|
||||||
|
<2> Create a second component template (`ct2`) that sets the number of replicas to 0 and defines a mapping
|
||||||
|
<3> Create an index template (`final-template`) that uses the component templates
|
||||||
|
<4> Show the configuration that would be applied to `myindex-1`
|
||||||
|
|
||||||
|
The response shows the index settings, mappings, and aliases applied by the `final-template`:
|
||||||
|
|
||||||
|
[source,console-result]
|
||||||
|
---------------------------------------------------------
|
||||||
|
{
|
||||||
|
"template" : {
|
||||||
|
"settings" : {
|
||||||
|
"index" : {
|
||||||
|
"number_of_shards" : "2",
|
||||||
|
"number_of_replicas" : "0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"mappings" : {
|
||||||
|
"properties" : {
|
||||||
|
"@timestamp" : {
|
||||||
|
"type" : "date"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"aliases" : { }
|
||||||
|
},
|
||||||
|
"overlapping" : [
|
||||||
|
{
|
||||||
|
"name" : "template_1",
|
||||||
|
"index_patterns" : [
|
||||||
|
"myindex*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
---------------------------------------------------------
|
||||||
|
|
@ -0,0 +1,300 @@
|
||||||
|
[[indices-simulate-template]]
|
||||||
|
=== Simulate index template API
|
||||||
|
++++
|
||||||
|
<titleabbrev>Simulate template</titleabbrev>
|
||||||
|
++++
|
||||||
|
|
||||||
|
experimental[]
|
||||||
|
|
||||||
|
Returns the index configuration that would be applied by a particular
|
||||||
|
<<indices-templates, index template>>.
|
||||||
|
|
||||||
|
////
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
PUT _index_template/template_1
|
||||||
|
{
|
||||||
|
"index_patterns": ["te*", "bar*"],
|
||||||
|
"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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"aliases": {
|
||||||
|
"mydata": { }
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"priority": 10,
|
||||||
|
"version": 3,
|
||||||
|
"_meta": {
|
||||||
|
"description": "my custom"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// TESTSETUP
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
DELETE _index_template/*
|
||||||
|
DELETE _component_template/*
|
||||||
|
--------------------------------------------------
|
||||||
|
// TEARDOWN
|
||||||
|
////
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
POST /_index_template/_simulate/template_1
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
[[simulate-template-api-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`POST /_index_template/_simulate/<index-template>`
|
||||||
|
|
||||||
|
|
||||||
|
[[simulate-template-api-path-params]]
|
||||||
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
|
`<index-template>`::
|
||||||
|
(Optional, string)
|
||||||
|
Name of the index template to simulate.
|
||||||
|
To test a template configuration before you add it to the cluster,
|
||||||
|
omit this parameter and specify the template configuration in the request body.
|
||||||
|
|
||||||
|
[[simulate-template-api-query-params]]
|
||||||
|
==== {api-query-parms-title}
|
||||||
|
////
|
||||||
|
`cause`::
|
||||||
|
(Optional, string) The reason for using the specified template for the simulation.
|
||||||
|
////
|
||||||
|
|
||||||
|
`create`::
|
||||||
|
(Optional, boolean) If `true`, the template passed in the body is
|
||||||
|
only used if no existing templates match the same index patterns.
|
||||||
|
If `false`, the simulation uses the template with the highest priority.
|
||||||
|
Note that the template is not permanently added or updated in either case;
|
||||||
|
it is only used for the simulation.
|
||||||
|
Defaults to `false`.
|
||||||
|
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
||||||
|
|
||||||
|
[[simulate-template-api-request-body]]
|
||||||
|
==== {api-request-body-title}
|
||||||
|
|
||||||
|
`composed_of`::
|
||||||
|
(Optional, array of strings)
|
||||||
|
Ordered list of component template names. Component templates are merged in the order
|
||||||
|
specified, meaning that the last component template specified has the highest precedence.
|
||||||
|
For an example, see
|
||||||
|
<<multiple-component-templates,Composing multiple component templates>>.
|
||||||
|
|
||||||
|
`index_patterns`::
|
||||||
|
(Required, array of strings)
|
||||||
|
Array of wildcard (`*`) expressions
|
||||||
|
used to match the names of indices during creation.
|
||||||
|
|
||||||
|
`priority`::
|
||||||
|
(Optional, integer)
|
||||||
|
Priority that determines what template is applied if there are multiple templates
|
||||||
|
that match the name of a new index.
|
||||||
|
The highest priority template takes precedence. Defaults to `0` (lowest priority).
|
||||||
|
|
||||||
|
`template`::
|
||||||
|
(Optional, object)
|
||||||
|
Template to apply.
|
||||||
|
+
|
||||||
|
.Properties of `template`
|
||||||
|
[%collapsible%open]
|
||||||
|
====
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases]
|
||||||
|
|
||||||
|
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 index templates externally.
|
||||||
|
This version is not automatically generated by {es}.
|
||||||
|
|
||||||
|
`_meta`::
|
||||||
|
(Optional, object)
|
||||||
|
User-specified metadata for the index template.
|
||||||
|
This information is not generated or used by {es}.
|
||||||
|
|
||||||
|
[role="child_attributes"]
|
||||||
|
[[simulate-template-api-response-body]]
|
||||||
|
==== {api-response-body-title}
|
||||||
|
|
||||||
|
`overlapping`::
|
||||||
|
(array) Any templates that were superseded by the specified template.
|
||||||
|
+
|
||||||
|
.Properties of `overlapping`
|
||||||
|
[%collapsible%open]
|
||||||
|
====
|
||||||
|
`index_patterns`::
|
||||||
|
(array) Index patterns that the superseded template applies to.
|
||||||
|
|
||||||
|
`name`::
|
||||||
|
(string) Name of the superseded template.
|
||||||
|
====
|
||||||
|
|
||||||
|
`template`::
|
||||||
|
(object)
|
||||||
|
The settings, mappings, and aliases that would be applied to matching indices.
|
||||||
|
+
|
||||||
|
.Properties of `template`
|
||||||
|
[%collapsible%open]
|
||||||
|
====
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases]
|
||||||
|
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]
|
||||||
|
|
||||||
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
|
||||||
|
====
|
||||||
|
|
||||||
|
[[simulate-template-api-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
[[simulate-existing-template-ex]]
|
||||||
|
===== Simulating an existing template
|
||||||
|
|
||||||
|
The following example creates and simulates a composed template:
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
PUT /_component_template/ct1 <1>
|
||||||
|
{
|
||||||
|
"template": {
|
||||||
|
"settings": {
|
||||||
|
"index.number_of_shards": 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT /_component_template/ct2 <2>
|
||||||
|
{
|
||||||
|
"template": {
|
||||||
|
"settings": {
|
||||||
|
"index.number_of_replicas": 0
|
||||||
|
},
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"@timestamp": {
|
||||||
|
"type": "date"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT /_index_template/final-template <3>
|
||||||
|
{
|
||||||
|
"index_patterns": ["myindex*"],
|
||||||
|
"composed_of": ["ct1", "ct2"],
|
||||||
|
"priority": 5
|
||||||
|
}
|
||||||
|
|
||||||
|
POST /_index_template/_simulate/final-template <4>
|
||||||
|
--------------------------------------------------
|
||||||
|
<1> Create a component template (`ct1`) that sets the number of shards to 2
|
||||||
|
<2> Create a component template (`ct2`) that sets the number of replicas to 0 and defines a mapping
|
||||||
|
<3> Create an index template (`final-template`) that uses the component templates
|
||||||
|
<4> Show the configuration applied by the `final-template`
|
||||||
|
|
||||||
|
The response shows the index settings, mappings, and aliases applied by the `final-template`:
|
||||||
|
|
||||||
|
[source,console-result]
|
||||||
|
---------------------------------------------------------
|
||||||
|
{
|
||||||
|
"template" : {
|
||||||
|
"settings" : {
|
||||||
|
"index" : {
|
||||||
|
"number_of_shards" : "2", <1>
|
||||||
|
"number_of_replicas" : "0" <2>
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"mappings" : { <3>
|
||||||
|
"properties" : {
|
||||||
|
"@timestamp" : {
|
||||||
|
"type" : "date"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"aliases" : { }
|
||||||
|
},
|
||||||
|
"overlapping" : [ ]
|
||||||
|
}
|
||||||
|
---------------------------------------------------------
|
||||||
|
<1> Number of shards from `ct1`
|
||||||
|
<2> Number of replicas from `ct2`
|
||||||
|
<3> Mappings from `ct1`
|
||||||
|
|
||||||
|
|
||||||
|
[[simulate-template-config-ex]]
|
||||||
|
===== Simulating an arbitrary template configuration
|
||||||
|
|
||||||
|
To see what settings will be applied by a template before you add it to the cluster,
|
||||||
|
you can pass a template configuration in the request body.
|
||||||
|
The specified template is used for the simulation if it has a higher priority than existing templates.
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
--------------------------------------------------
|
||||||
|
POST /_index_template/_simulate
|
||||||
|
{
|
||||||
|
"index_patterns": ["myindex*"],
|
||||||
|
"composed_of": ["ct2"],
|
||||||
|
"priority": 10,
|
||||||
|
"template": {
|
||||||
|
"settings": {
|
||||||
|
"index.number_of_replicas": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------
|
||||||
|
// TEST[continued]
|
||||||
|
|
||||||
|
The response shows any overlapping templates with a lower priority.
|
||||||
|
|
||||||
|
[source,console-result]
|
||||||
|
---------------------------------------------------------
|
||||||
|
{
|
||||||
|
"template" : {
|
||||||
|
"settings" : {
|
||||||
|
"index" : {
|
||||||
|
"number_of_replicas" : "1"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"mappings" : {
|
||||||
|
"properties" : {
|
||||||
|
"@timestamp" : {
|
||||||
|
"type" : "date"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"aliases" : { }
|
||||||
|
},
|
||||||
|
"overlapping" : [
|
||||||
|
{
|
||||||
|
"name" : "final-template",
|
||||||
|
"index_patterns" : [
|
||||||
|
"myindex*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
---------------------------------------------------------
|
||||||
Loading…
Reference in New Issue