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}

* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
<<security-privileges>>.


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

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

[[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::{docdir}/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.

--

[[update-analysislimits]]`analysis_limits`.`model_memory_limit`::
(long or string) 
include::{docdir}/ml/ml-shared.asciidoc[tag=model-memory-limit]
+
--
NOTE: You can update the `analysis_limits` only while the job is closed. The 
`model_memory_limit` property value cannot be decreased below the current usage.
 
TIP: If the `memory_status` property in the
<<ml-get-snapshot-results,`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`.

--

`background_persist_interval`::
(<<time-units,time units>>)
include::{docdir}/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::{docdir}/ml/ml-shared.asciidoc[tag=custom-settings]

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

`detectors`::
(array) An array of detector update objects.

`detectors`.`custom_rules`:::
+
--
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules]

`detectors`.`custom_rules`.`actions`:::
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-actions]

`detectors`.`custom_rules`.`scope`:::
(object)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope]

`detectors`.`custom_rules`.`scope`.`filter_id`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-id]

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

`detectors`.`custom_rules`.`conditions`:::
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions]

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

`detectors`.`custom_rules`.`conditions`.`operator`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-operator]

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

`detectors`.`description`:::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-description]
`detectors`.`detector_index`:::
(integer)
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-index]

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

`model_plot_config`::
(object)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config]

`model_plot_config`.`enabled`:::
(boolean)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config-enabled]

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

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

`renormalization_window_days`::
(long)
include::{docdir}/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::{docdir}/ml/ml-shared.asciidoc[tag=results-retention-days]


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

[source,console]
--------------------------------------------------
POST _ml/anomaly_detectors/total-requests/_update
{
  "description":"An updated job",
  "groups": ["group1","group2"],
  "model_plot_config": {
    "enabled": true
  },
  "analysis_limits": {
    "model_memory_limit": "1024mb"
  },
  "renormalization_window_days": 30,
  "background_persist_interval": "2h",
  "model_snapshot_retention_days": 7,
  "results_retention_days": 60,
  "custom_settings": {
    "custom_urls" : [{
      "url_name" : "Lookup IP",
      "url_value" : "http://geoiplookup.net/ip/$clientip$"
    }]
  }
}
--------------------------------------------------
// TEST[skip:setup:server_metrics_job]

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

[source,console-result]
----
{
  "job_id": "total-requests",
  "job_type": "anomaly_detector",
  "job_version": "7.0.0-alpha1",
  "groups": [
    "group1",
    "group2"
  ],
  "description": "An updated job",
  "create_time": 1518808660505,
  "analysis_config": {
    "bucket_span": "10m",
    "detectors": [
      {
        "detector_description": "Sum of total",
        "function": "sum",
        "field_name": "total",
        "detector_index": 0
      }
    ],
    "influencers": []
  },
  "analysis_limits": {
    "model_memory_limit": "1024mb",
    "categorization_examples_limit": 4
  },
  "data_description": {
    "time_field": "timestamp",
    "time_format": "epoch_ms"
  },
  "model_plot_config": {
    "enabled": true
  },
  "renormalization_window_days": 30,
  "background_persist_interval": "2h",
  "model_snapshot_retention_days": 7,
  "results_retention_days": 60,
  "custom_settings": {
    "custom_urls": [
      {
        "url_name": "Lookup IP",
        "url_value": "http://geoiplookup.net/ip/$clientip$"
      }
    ]
  },
  "results_index_name": "shared",
  "allow_lazy_open": false
}
----
// TESTRESPONSE[s/"job_version": "7.0.0-alpha1"/"job_version": $body.job_version/]
// TESTRESPONSE[s/"create_time": 1518808660505/"create_time": $body.create_time/]