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. If the user who created the transform does not
have the required privileges on the source and destination indices, the
transform starts but then fails when it attempts the unauthorized operation.

[[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,js]
----
{
  "acknowledged" : true
}
----
// TESTRESPONSE