Update data frame analytics jobs API

Updates an existing data frame analytics job.

This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.

Request

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

Prerequisites

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.

The data frame analytics job remembers which roles the user who updated it had at the time of the update. When you start the job, it performs the analysis using those same roles. If you provide secondary authorization headers, those credentials are used instead.

Description

This API updates an existing data frame analytics job that performs an analysis on the source indices and stores the outcome in a destination index.

Path parameters

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

Request body

allow_lazy_start

(Optional, boolean) Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node. The default is false; if a machine learning node with capacity to run the job cannot immediately be found, the API returns an error. However, this is also subject to the cluster-wide xpack.ml.max_lazy_ml_nodes setting. See Advanced machine learning settings. If this option is set to true, the API does not return an error and the job waits in the starting state until sufficient machine learning node capacity is available.

description

(Optional, string) A description of the job.

max_num_threads

(Optional, integer) The maximum number of threads to be used by the analysis. The default value is 1. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.

model_memory_limit

(Optional, string) The approximate maximum amount of memory resources that are permitted for analytical processing. The default value for data frame analytics jobs is 1gb. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting. For more information, see Machine learning settings.

Examples

Updating model memory limit example

The following example shows how to update the model memory limit for the existing data frame analytics configuration.

  1. POST _ml/data_frame/analytics/model-flight-delays/_update
  2. {
  3. "model_memory_limit": "200mb"
  4. }