Start data frame analytics jobs API

edit

Starts a data frame analytics job.

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

Request

edit

POST _ml/data_frame/analytics/<data_frame_analytics_id>/_start

Prerequisites

edit

If the Elasticsearch security features are enabled, you must have the following built-in roles and privileges:

  • machine_learning_admin
  • source indices: read, view_index_metadata
  • destination index: read, create_index, manage and index

For more information, see Built-in roles, Security privileges, and Machine learning security privileges.

Description

edit

A data frame analytics job can be started and stopped multiple times throughout its lifecycle.

If the destination index does not exist, it is created automatically the first time you start the data frame analytics job. The index.number_of_shards and index.number_of_replicas settings for the destination index are copied from the source index. If there are multiple source indices, the destination index copies the highest setting values. The mappings for the destination index are also copied from the source indices. If there are any mapping conflicts, the job fails to start.

If the destination index exists, it is used as is. You can therefore set up the destination index in advance with custom settings and mappings.

When Elasticsearch security features are enabled, the data frame analytics job remembers which user created it and runs the job using those credentials. If you provided secondary authorization headers when you created the job, those credentials are used.

Path parameters

edit
<data_frame_analytics_id>
(Required, string) Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

Query parameters

edit
timeout
(Optional, time units) Controls the amount of time to wait until the data frame analytics job starts. Defaults to 20 seconds.

Response body

edit
acknowledged
(Boolean) For a successful response, this value is always true. On failure, an exception is returned instead.
node
(string) The ID of the node that the job was started on. If the job is allowed to open lazily and has not yet been assigned to a node, this value is an empty string.

Examples

edit

The following example starts the loganalytics data frame analytics job:

POST _ml/data_frame/analytics/loganalytics/_start

When the data frame analytics job starts, you receive the following results:

{
  "acknowledged" : true,
  "node" : "node-1"
}