* [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>>
|
||||
* <<getting-component-templates>>
|
||||
* <<indices-template-exists>>
|
||||
|
||||
[float]
|
||||
[[component-template-apis]]
|
||||
=== Component templates:
|
||||
* <<indices-component-template>>
|
||||
* <<indices-simulate-index>>
|
||||
* <<indices-simulate-template>>
|
||||
|
||||
[float]
|
||||
[[monitoring]]
|
||||
|
|
@ -148,6 +145,10 @@ include::indices/rollover-index.asciidoc[]
|
|||
|
||||
include::indices/shrink-index.asciidoc[]
|
||||
|
||||
include::indices/simulate-index.asciidoc[]
|
||||
|
||||
include::indices/simulate-template.asciidoc[]
|
||||
|
||||
include::indices/split-index.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