2019-03-22 00:38:00 +08:00
[role="xpack"]
[testenv="basic"]
2019-09-21 04:26:57 +08:00
[[start-transform]]
2020-07-23 01:55:48 +08:00
= Start {transform} API
2019-05-01 01:46:13 +08:00
[subs="attributes"]
2019-03-22 00:38:00 +08:00
++++
2019-12-18 01:01:31 +08:00
<titleabbrev>Start {transform}</titleabbrev>
2019-03-22 00:38:00 +08:00
++++
2019-09-16 23:28:19 +08:00
Starts one or more {transforms}.
2019-03-22 00:38:00 +08:00
2019-09-21 04:26:57 +08:00
[[start-transform-request]]
2020-07-23 01:55:48 +08:00
== {api-request-title}
2019-03-22 00:38:00 +08:00
2019-10-07 22:21:51 +08:00
`POST _transform/<transform_id>/_start`
2019-03-22 00:38:00 +08:00
2019-09-21 04:26:57 +08:00
[[start-transform-prereqs]]
2020-07-23 01:55:48 +08:00
== {api-prereq-title}
2019-06-13 01:13:04 +08:00
2021-05-06 21:19:28 +08:00
Requires the following privileges:
2020-04-06 23:06:22 +08:00
2021-05-06 21:19:28 +08:00
* cluster: `manage_transform` (the `transform_admin` built-in role grants this
privilege)
* source indices: `read`, `view_index_metadata`.
2019-03-22 00:38:00 +08:00
2019-09-21 04:26:57 +08:00
[[start-transform-desc]]
2020-07-23 01:55:48 +08:00
== {api-description-title}
2019-07-23 06:29:59 +08:00
2021-06-03 04:45:01 +08:00
When you start a {transform}, it creates the destination index if it does not
already exist. The `number_of_shards` is set to `1` and the
2019-07-25 02:09:06 +08:00
`auto_expand_replicas` is set to `0-1`.
2021-06-03 04:45:01 +08:00
If it is a pivot {transform}, it deduces the mapping definitions for the
destination index from the source indices and the transform aggregations. If
fields in the destination index are derived from scripts (as in the case of
`scripted_metric` or `bucket_script` aggregations), the {transform} uses
<<dynamic-mapping,dynamic mappings>> unless an index template exists.
If it is a latest {transform}, it does not deduce mapping definitions; it uses
dynamic mappings.
TIP: To use explicit mappings, create the destination index before you start the {transform}. Alternatively, you can create an index template, though it does not affect the
deduced mappings in a pivot {transform}.
2019-07-25 02:09:06 +08:00
2019-09-16 23:28:19 +08:00
When the {transform} starts, a series of validations occur to ensure
2019-07-25 02:09:06 +08:00
its success. If you deferred validation when you created the
2019-09-16 23:28:19 +08:00
{transform}, they occur when you start the {transform}--with the
2019-07-26 06:03:57 +08:00
exception of privilege checks. When {es} {security-features} are enabled, the
2019-09-16 23:28:19 +08:00
{transform} remembers which roles the user that created it had at the
2019-07-26 06:03:57 +08:00
time of creation and uses those same roles. If those roles do not have the
required privileges on the source and destination indices, the
2019-09-16 23:28:19 +08:00
{transform} fails when it attempts unauthorized operations.
2019-07-23 06:29:59 +08:00
2019-09-21 04:26:57 +08:00
[[start-transform-path-parms]]
2020-07-23 01:55:48 +08:00
== {api-path-parms-title}
2019-06-27 04:46:21 +08:00
2019-09-21 04:26:57 +08:00
`<transform_id>`::
2019-12-18 01:01:31 +08:00
(Required, string)
2020-06-02 02:46:10 +08:00
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-id]
2019-03-22 00:38:00 +08:00
2019-09-21 04:26:57 +08:00
[[start-transform-example]]
2020-07-23 01:55:48 +08:00
== {api-examples-title}
2019-03-22 00:38:00 +08:00
2019-09-10 01:13:41 +08:00
[source,console]
2019-03-22 00:38:00 +08:00
--------------------------------------------------
2019-10-07 22:21:51 +08:00
POST _transform/ecommerce_transform/_start
2019-03-22 00:38:00 +08:00
--------------------------------------------------
// TEST[skip:set up kibana samples]
2019-09-16 23:28:19 +08:00
When the {transform} starts, you receive the following results:
2019-09-06 04:47:18 +08:00
[source,console-result]
2019-03-22 00:38:00 +08:00
----
{
2019-05-29 17:13:37 +08:00
"acknowledged" : true
2019-03-22 00:38:00 +08:00
}
----