OpenSearch/docs/reference/ml/apis/update-job.asciidoc

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

Updates certain properties of a job.

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

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

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

`job_id` (required)::
  (string) Identifier for the job

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

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

[cols="<,<,<",options="header",]
|=======================================================================
|Name |Description |Requires Restart

|`analysis_limits`: `model_memory_limit` |The approximate maximum amount of
memory resources required for analytical processing. See <<ml-apilimits>>. | Yes

|`background_persist_interval` |Advanced configuration option. The time between
each periodic persistence of the model. See <<ml-job-resource>>. | Yes

|`custom_settings` |Contains custom meta data about the job. | No

|`description` |A description of the job. See <<ml-job-resource>>. | No

|`detectors` |An array of <<ml-detector-update, detector update objects>>. | No

|`groups` |A list of job groups. See <<ml-job-resource>>. | No

|`model_plot_config`: `enabled` |If true, enables calculation and storage of the
model bounds for each entity that is being analyzed.
See <<ml-apimodelplotconfig>>. | No

|`model_snapshot_retention_days` |The time in days that model snapshots are
retained for the job. See <<ml-job-resource>>. | Yes

|`renormalization_window_days` |Advanced configuration option. The period over
which adjustments to the score are applied, as new data is seen.
See <<ml-job-resource>>. | Yes

|`results_retention_days` |Advanced configuration option. The number of days
for which job results are retained. See <<ml-job-resource>>. | Yes

|=======================================================================

For those properties that have `Requires Restart` set to `Yes` in this table,
if the job is open when you make the update, you must stop the data feed, close
the job, then restart the data feed and open the job for the changes to take
effect.

[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.
* If the `memory_status` property in the `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 this job with an increased `model_memory_limit`.
--

[[ml-detector-update]]
==== Detector Update Objects

A detector update object has the following properties:

`detector_index`::
  (integer) The identifier of the detector to update.

`description`::
  (string) The new description for the detector.

`custom_rules`::
  (array) The new list of <<ml-detector-custom-rule, rules>> for the detector.

No other detector property can be updated.

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

You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{stack-ov}/security-privileges.html[Security privileges].

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

The following example updates the `total-requests` job:

[source,js]
--------------------------------------------------
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$"
    }]
  }
}
--------------------------------------------------
// CONSOLE
// TEST[skip:setup:server_metrics_job]

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

[source,js]
----
{
  "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"
}
----
// TESTRESPONSE[s/"job_version": "7.0.0-alpha1"/"job_version": $body.job_version/]
// TESTRESPONSE[s/"create_time": 1518808660505/"create_time": $body.create_time/]