elasticsearch/docs/reference/ml/df-analytics/apis/update-dfanalytics.asciidoc

[role="xpack"]
[[update-dfanalytics]]
= Update {dfanalytics-jobs} API
[subs="attributes"]
++++
<titleabbrev>Update {dfanalytics-jobs}</titleabbrev>
++++

Updates an existing {dfanalytics-job}.


[[ml-update-dfanalytics-request]]
== {api-request-title}

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


[[ml-update-dfanalytics-prereq]]
== {api-prereq-title}

Requires the following privileges:

* cluster: `manage_ml` (the `machine_learning_admin` built-in role grants this 
  privilege)
* source indices: `read`, `view_index_metadata`
* destination index: `read`, `create_index`, `manage` and `index`

NOTE: The {dfanalytics-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
<<http-clients-secondary-authorization,secondary authorization headers>>, 
those credentials are used instead.


[[ml-update-dfanalytics-desc]]
== {api-description-title}

This API updates an existing {dfanalytics-job} that performs an analysis on the source
indices and stores the outcome in a destination index.


[[ml-update-dfanalytics-path-params]]
== {api-path-parms-title}

`<data_frame_analytics_id>`::
(Required, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics-define]

[role="child_attributes"]
[[ml-update-dfanalytics-request-body]]
== {api-request-body-title}

`allow_lazy_start`::
(Optional, Boolean) 
Specifies whether this job can start when there is insufficient {ml} node 
capacity for it to be immediately assigned to a node. The default is `false`; if
a {ml} 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-ml-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 {ml} node capacity is available.

`description`::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=description-dfa]

`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)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-memory-limit-dfa]

[[ml-update-dfanalytics-example]]
== {api-examples-title}

[[ml-update-dfanalytics-example-preprocess]]
=== Updating model memory limit example

The following example shows how to update the model memory limit for the existing {dfanalytics} configuration.

[source,console]
--------------------------------------------------
POST _ml/data_frame/analytics/loganalytics/_update
{
  "model_memory_limit": "200mb"
}
--------------------------------------------------
// TEST[skip:setup kibana sample data]

When the job is updated, the response contains its configuration with
the updated values. For example:

[source,console-result]
----
{
  "id" : "loganalytics",
  "create_time" : 1656364565517,
  "version" : "8.4.0",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "description" : "Outlier detection on log data",
  "source" : {
    "index" : [
      "logdata"
    ],
    "query" : {
      "match_all" : { }
    }
  },
  "dest" : {
    "index" : "logdata_out",
    "results_field" : "ml"
  },
  "analysis" : {
    "outlier_detection" : {
      "compute_feature_influence" : true,
      "outlier_fraction" : 0.05,
      "standardization_enabled" : true
    }
  },
  "model_memory_limit" : "200mb",
  "allow_lazy_start" : false,
  "max_num_threads" : 1
}
----