[role="xpack"]
[testenv="platinum"]
[[ml-update-datafeed]]
=== Update {dfeeds} API

[subs="attributes"]
++++
<titleabbrev>Update {dfeeds}</titleabbrev>
++++

Updates certain properties of a {dfeed}.


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

`POST _ml/datafeeds/<feed_id>/_update`


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

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


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

If you update a {dfeed} property, you must stop and start the {dfeed} for the 
change to be applied.

IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
which roles the user who updated it had at the time of update and runs the query
using those same roles.

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

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

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

The following properties can be updated after the {dfeed} is created:

`aggregations`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=aggregations]

`chunking_config`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=chunking-config]
  
`delayed_data_check_config`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=delayed-data-check-config]

`frequency`::
(Optional, <<time-units, time units>>)
include::{docdir}/ml/ml-shared.asciidoc[tag=frequency]

`indices`::
(Optional, array)
include::{docdir}/ml/ml-shared.asciidoc[tag=indices]

`max_empty_searches`::
(Optional, integer)
include::{docdir}/ml/ml-shared.asciidoc[tag=max-empty-searches]
+
--
The special value `-1` unsets this setting.
--

`query`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=query]
+
--
WARNING: If you change the query, the analyzed data is also changed. Therefore,
the required time to learn might be long and the understandability of the
results is unpredictable. If you want to make significant changes to the source
data, we would recommend you clone it and create a second job containing the
amendments. Let both run in parallel and close one when you are satisfied with
the results of the other job.

--

`query_delay`::
(Optional, <<time-units, time units>>)
include::{docdir}/ml/ml-shared.asciidoc[tag=query-delay]

`script_fields`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=script-fields]

`scroll_size`::
(Optional, unsigned integer)
include::{docdir}/ml/ml-shared.asciidoc[tag=scroll-size]


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

The following example updates the query for the `datafeed-total-requests`
{dfeed} so that only log entries of error level are analyzed:

[source,console]
--------------------------------------------------
POST _ml/datafeeds/datafeed-total-requests/_update
{
  "query": {
    "term": {
      "level": "error"
    }
  }
}
--------------------------------------------------
// TEST[skip:setup:server_metrics_datafeed]


When the {dfeed} is updated, you receive the full {dfeed} configuration with
with the updated values:

[source,console-result]
----
{
  "datafeed_id": "datafeed-total-requests",
  "job_id": "total-requests",
  "query_delay": "83474ms",
  "indices": ["server-metrics"],
  "query": {
    "term": {
      "level": {
        "value": "error",
        "boost": 1.0
      }
    }
  },
  "scroll_size": 1000,
  "chunking_config": {
    "mode": "auto"
  }
}
----
// TESTRESPONSE[s/"query.boost": "1.0"/"query.boost": $body.query.boost/]