[role="xpack"]
[[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}

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

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

You can only update a {dfeed} property while the {dfeed} is stopped.
However, it is possible to stop a {dfeed}, update one of its properties,
and restart it without closing the associated job.

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. If you provide
<<http-clients-secondary-authorization,secondary authorization headers>>, those
credentials are used instead.

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

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

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

`allow_no_indices`::
(Optional, Boolean) If `true`, wildcard indices expressions that resolve into no
concrete indices are ignored. This includes the `_all` string or when no indices
are specified. Defaults to `true`.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=ignore_throttled]

`ignore_unavailable`::
(Optional, Boolean) If `true`, unavailable indices (missing or closed) are
ignored. Defaults to `false`.

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

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

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

`chunking_config`::
(Optional, object)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=chunking-config]
+
.Properties of `chunking_config`
[%collapsible%open]
====
`mode`:::
(string)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=mode]

`time_span`:::
(<<time-units,time units>>)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=time-span]
====

`delayed_data_check_config`::
(Optional, object)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=delayed-data-check-config]
+
.Properties of `delayed_data_check_config`
[%collapsible%open]
====
`check_window`::
(<<time-units,time units>>)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=delayed-data-check-config-check-window]

`enabled`::
(Boolean)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=delayed-data-check-config-enabled]
====

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

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

`indices_options`::
(Optional, object)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=indices-options]

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

`query`::
(Optional, object)
include::{es-ref-dir}/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::{es-ref-dir}/ml/ml-shared.asciidoc[tag=query-delay]

`runtime_mappings`::
(Optional, object)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=runtime-mappings]

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

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


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

[source,console]
--------------------------------------------------
POST _ml/datafeeds/datafeed-test-job/_update
{
  "query": {
    "term": {
      "geo.src": "US"
    }
  }
}
--------------------------------------------------
// TEST[skip:setup sample web logs]

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

[source,console-result]
----
{
  "datafeed_id" : "datafeed-test-job",
  "job_id" : "test-job",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "query_delay" : "64489ms",
  "chunking_config" : {
    "mode" : "auto"
  },
  "indices_options" : {
    "expand_wildcards" : [
      "open"
    ],
    "ignore_unavailable" : false,
    "allow_no_indices" : true,
    "ignore_throttled" : true
  },
  "query" : {
    "term" : {
      "geo.src" : "US"
    }
  },
  "indices" : [
    "kibana_sample_data_logs"
  ],
  "scroll_size" : 1000,
  "delayed_data_check_config" : {
    "enabled" : true
  }
}
----