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

[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) Identifier for the {dfeed}.

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

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

`aggregations`::
  (Optional, object) If set, the {dfeed} performs aggregation searches. For more
  information, see <<ml-datafeed-resource>>.

`chunking_config`::
  (Optional, object) Specifies how data searches are split into time chunks. See
  <<ml-datafeed-chunking-config>>.
  
`delayed_data_check_config`::
  (Optional, object) Specifies whether the data feed checks for missing data and 
  the size of the window. See <<ml-datafeed-delayed-data-check-config>>.  

`frequency`::
  (Optional, <<time-units, time units>>) The interval at which scheduled queries 
  are made while the {dfeed} runs in real time. The default value is either the 
  bucket span for short bucket spans, or, for longer bucket spans, a sensible 
  fraction of the bucket span. For example: `150s`.

`indices`::
  (Optional, array) An array of index names. Wildcards are supported. For
  example: `["it_ops_metrics", "server*"]`.

`query`::
  (Optional, object) The {es} query domain-specific language (DSL). This value
  corresponds to the query object in an {es} search POST body. All the options
  that are supported by {es} can be used, as this object is passed verbatim to
  {es}. By default, this property has the following value:
  `{"match_all": {"boost": 1}}`.
+
--
WARNING: If you change the query, then the analyzed data will also be 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>>) The number of seconds behind real-time 
  that data is queried. For example, if data from 10:04 a.m. might not be 
  searchable in {es} until 10:06 a.m., set this property to 120 seconds. The 
  default value is `60s`.

`script_fields`::
  (Optional, object) Specifies scripts that evaluate custom expressions and
  returns script fields to the {dfeed}. The
  <<ml-detectorconfig,detector configuration objects>> in a job can contain
  functions that use these script fields. For more information, see
  <<request-body-search-script-fields,Script fields>>.

`scroll_size`::
  (Optional, unsigned integer) The `size` parameter that is used in {es}
  searches. The default value is `1000`.

`max_empty_searches`::
  (Optional, integer) If a real-time {dfeed} has never seen any data (including
  during any initial training period) then it will automatically stop itself
  and close its associated job after this many real-time searches that return
  no documents. In other words, it will stop after `frequency` times
  `max_empty_searches` of real-time operation. If not set
  then a {dfeed} with no end time that sees no data will remain started until
  it is explicitly stopped. The special value `-1` unsets this setting.

For more information about these properties, see <<ml-datafeed-resource>>.


[[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/]