elasticsearch/docs/reference/transform/apis/start-transform.asciidoc

[role="xpack"]
[[start-transform]]
= Start {transform} API

[subs="attributes"]
++++
<titleabbrev>Start {transform}</titleabbrev>
++++

Starts a {transform}.

[[start-transform-request]]
== {api-request-title}

`POST _transform/<transform_id>/_start`

[[start-transform-prereqs]]
== {api-prereq-title}

Requires the following privileges:

* cluster: `manage_transform` (the `transform_admin` built-in role grants this
  privilege)
* source indices: `read`, `view_index_metadata`.
* destination index: `read`, `create_index`, `index`. If a `retention_policy` is configured, the `delete` privilege is
  also required.

[[start-transform-desc]]
== {api-description-title}

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
`auto_expand_replicas` is set to `0-1`.

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}.

When the {transform} starts, a series of validations occur to ensure
its success. If you deferred validation when you created the
{transform}, they occur when you start the {transform}--with the
exception of privilege checks. When {es} {security-features} are enabled, the
{transform} remembers which roles the user that created it had at the
time of creation and uses those same roles. If those roles do not have the
required privileges on the source and destination indices, the
{transform} fails when it attempts unauthorized operations.

[[start-transform-path-parms]]
== {api-path-parms-title}

`<transform_id>`::
(Required, string)
Identifier for the {transform}.

[[start-transform-query-parms]]
== {api-query-parms-title}

`timeout`::
(Optional, time)
Period to wait for a response. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to `30s`.


[[start-transform-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
POST _transform/ecommerce_transform/_start
--------------------------------------------------
// TEST[skip:set up kibana samples]

When the {transform} starts, you receive the following results:

[source,console-result]
----
{
  "acknowledged" : true
}
----