Update datafeeds API

edit

Updates certain properties of a datafeed.

Request

edit

POST _ml/datafeeds/<feed_id>/_update

Prerequisites

edit
  • If Elasticsearch security features are enabled, you must have manage_ml, or manage cluster privileges to use this API. For more information, see Security privileges.

Description

edit

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

Path parameters

edit
feed_id
(Required, string) Identifier for the datafeed.

Request body

edit

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

aggregations
(object) If set, the datafeed performs aggregation searches. For more information, see Datafeed resources.
chunking_config
(object) Specifies how data searches are split into time chunks. See Chunking configuration objects.
delayed_data_check_config
(object) Specifies whether the data feed checks for missing data and the size of the window. See Delayed data check configuration objects.
frequency
(Optional, time units) The interval at which scheduled queries are made while the datafeed 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
(array) An array of index names. Wildcards are supported. For example: ["it_ops_metrics", "server*"].
job_id
(Optional, string) A numerical character string that uniquely identifies the anomaly detection job.
query

(object) The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {"boost": 1}}.

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) 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 Elasticsearch until 10:06 a.m., set this property to 120 seconds. The default value is 60s.
script_fields
(object) Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields. For more information, see Script Fields.
scroll_size
(unsigned integer) The size parameter that is used in Elasticsearch searches. The default value is 1000.

For more information about these properties, see Datafeed resources.

Security Integration

edit

When Elasticsearch security features are enabled, your datafeed remembers which roles the user who updated it had at the time of update and runs the query using those same roles.

Examples

edit

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

POST _ml/datafeeds/datafeed-total-requests/_update
{
  "query": {
    "term": {
      "level": "error"
    }
  }
}

When the datafeed is updated, you receive the full datafeed configuration with with the updated values:

{
  "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"
  }
}