elasticsearch/docs/reference/ml/anomaly-detection/apis/update-job.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ml-update-job]]
= Update {anomaly-jobs} API
++++
<titleabbrev>Update jobs</titleabbrev>
++++

Updates certain properties of an {anomaly-job}.

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

`POST _ml/anomaly_detectors/<job_id>/_update`

[[ml-update-job-prereqs]]
== {api-prereq-title}

Requires the `manage_ml` cluster privilege. This privilege is included in the 
`machine_learning_admin` built-in role.

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

`<job_id>`::
(Required, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]

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

The following properties can be updated after the job is created:

`allow_lazy_open`::
(Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=allow-lazy-open]
+
--
NOTE: If the job is open when you make the update, you must stop the {dfeed},
close the job, then reopen the job and restart the {dfeed} for the changes to take effect.

--
//Begin analysis_limits
[[update-analysislimits]]`analysis_limits`::
(Optional, object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=analysis-limits]
+
You can update the `analysis_limits` only while the job is closed.
+
.Properties of `analysis_limits`
[%collapsible%open]
====
`model_memory_limit`:::
(long or string) 
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-memory-limit-ad]
+
--
[NOTE]
=======
* You cannot decrease the `model_memory_limit` value below the current usage. To
determine the current usage, refer to the `model_bytes` value in
the <<ml-get-job-stats,get job stats>> API.
* If the `memory_status` property in the
<<modelsizestats,`model_size_stats` object>> has a value of 
`hard_limit`, this means that it was unable to process some data. You might want 
to re-run the job with an increased `model_memory_limit`.
=======
--
====
//End analysis_limits

`background_persist_interval`::
(<<time-units,time units>>)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=background-persist-interval]
+
--
NOTE: If the job is open when you make the update, you must stop the {dfeed},
close the job, then reopen the job and restart the {dfeed} for the changes to take effect.

--

[[update-customsettings]]`custom_settings`::
(object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-settings]

`daily_model_snapshot_retention_after_days`::
(long)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=daily-model-snapshot-retention-after-days]

`description`::
(string) A description of the job.

//Begin detectors
`detectors`::
(array) An array of detector update objects.
+
.Properties of `detectors`
[%collapsible%open]
====

//Begin detectors.custom_rules
`custom_rules`:::
(array)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules]
+
.Properties of `custom_rules`
[%collapsible%open]
=====

`actions`:::
(array)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-actions]

// Begin detectors.custom_rules.conditions
`conditions`:::
(array)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions]
+
.Properties of `conditions`
[%collapsible%open]
======

`applies_to`::::
(string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-applies-to]

`operator`::::
(string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-operator]

`value`::::
(double)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-value]
======
//End detectors.custom_rules.conditions

//Begin detectors.custom_rules.scope
`scope`:::
(object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-scope]
+
.Properties of `scope`
[%collapsible%open]
======
`filter_id`::::
(string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-id]

`filter_type`::::
(string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-type]
======
//End detectors.custom_rules.scope
=====
//End detectors.custom_rules

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

`detector_index`:::
(integer)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=detector-index]
+
--
If you want to update a specific detector, you must use this identifier. You
cannot, however, change the `detector_index` value for a detector.
--
====
//End detectors

`groups`::
(array of strings)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=groups]

//Begin model_plot_config
`model_plot_config`::
(object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-plot-config]
+
.Properties of `model_plot_config`
[%collapsible%open]
====
`annotations_enabled`:::
(Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-plot-config-annotations-enabled]

`enabled`:::
(Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-plot-config-enabled]

`terms`:::
experimental[] (string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-plot-config-terms]
====
//End model_plot_config

`model_prune_window`::
(<<time-units,time units>>)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-prune-window]

`model_snapshot_retention_days`::
(long)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-snapshot-retention-days]

//Begin per_partition_categorization
`per_partition_categorization`:::
(object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=per-partition-categorization]
+
.Properties of `per_partition_categorization`
[%collapsible%open]
====
`enabled`:::
(Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=per-partition-categorization-enabled]

`stop_on_warn`:::
(Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=per-partition-categorization-stop-on-warn]
====
//End per_partition_categorization

`renormalization_window_days`::
(long)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=renormalization-window-days]
+
--
NOTE: If the job is open when you make the update, you must stop the {dfeed},
close the job, then reopen the job and restart the {dfeed} for the changes to take effect.

--

`results_retention_days`::
(long)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=results-retention-days]


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

[source,console]
--------------------------------------------------
POST _ml/anomaly_detectors/low_request_rate/_update
{
  "description":"An updated job",
  "detectors": {
    "detector_index": 0,
    "description": "An updated detector description"
  },
  "groups": ["kibana_sample_data","kibana_sample_web_logs"],
  "model_plot_config": {
    "enabled": true
  },
  "renormalization_window_days": 30,
  "background_persist_interval": "2h",
  "model_snapshot_retention_days": 7,
  "results_retention_days": 60
}
--------------------------------------------------
// TEST[skip:setup:Kibana sample data]

When the {anomaly-job} is updated, you receive a summary of the job
configuration information, including the updated property values. For example:

[source,js]
----
{
  "job_id" : "low_request_rate",
  "job_type" : "anomaly_detector",
  "job_version" : "8.0.0",
  "groups" : [
    "kibana_sample_data",
    "kibana_sample_web_logs"
  ],
  "description" : "An updated job",
  "create_time" : 1576623023709,
  "analysis_config" : {
    "bucket_span" : "1h",
    "summary_count_field_name" : "doc_count",
    "detectors" : [
      {
        "detector_description" : "An updated detector description",
        "function" : "low_count",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ]
  },
  ...
}
----