OpenSearch/docs/reference/data-frames/apis/start-transform.asciidoc

[role="xpack"]
[testenv="basic"]
[[start-data-frame-transform]]
=== Start {dataframe-transforms} API

[subs="attributes"]
++++
<titleabbrev>Start {dataframe-transforms}</titleabbrev>
++++

Starts one or more {dataframe-transforms}.

beta[]

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

`POST _data_frame/transforms/<data_frame_transform_id>/_start`

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

* If the {es} {security-features} are enabled, you must have
`manage_data_frame_transforms` cluster privileges to use this API. You must also
have `view_index_metadata` privileges on the source index for the
{dataframe-transform}. For more information, see
{stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].

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

When you start a {dataframe-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`.

The transform deduces the mapping definitions from the source indices. For
scripted fields, it uses <<dynamic-mapping,dynamic mappings>>. If a field in the
destination index is created by `scripted_metric` or `bucket_script`
aggregations, the transform uses dynamic mappings unless a template exists or
the destination index already exists. Mapping definitions in the destination
index take precedence over dynamic mappings and templates.

When the {dataframe-transform} starts, a series of validations occur to ensure
its success. If you deferred validation when you created the
{dataframe-transform}, they occur when you start the transform--with the
exception of privilege checks. When {es} {security-features} are enabled, the
{dataframe-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
{dataframe-transform} fails when it attempts unauthorized operations.

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

`<data_frame_transform_id>`::
  (Required, string) Identifier for the {dataframe-transform}. This identifier
  can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and
  underscores. It must start and end with alphanumeric characters.

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

[source,js]
--------------------------------------------------
POST _data_frame/transforms/ecommerce_transform/_start
--------------------------------------------------
// CONSOLE
// TEST[skip:set up kibana samples]

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

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