OpenSearch/docs/en/rest-api/ml/update-datafeed.asciidoc

136 lines
3.6 KiB
Plaintext

[role="xpack"]
[[ml-update-datafeed]]
=== Update {dfeeds-cap} API
++++
<titleabbrev>Update {dfeeds-cap}</titleabbrev>
++++
The update {dfeed} API enables you to update certain properties of a {dfeed}.
==== Request
`POST _xpack/ml/datafeeds/<feed_id>/_update`
//===== Description
==== Path Parameters
`feed_id` (required)::
(string) Identifier for the {dfeed}
==== Request Body
The following properties can be updated after the {dfeed} is created:
`aggregations`::
(object) If set, the {dfeed} performs aggregation searches.
For more information, see <<ml-datafeed-resource>>.
`chunking_config`::
(object) Specifies how data searches are split into time chunks.
See <<ml-datafeed-chunking-config>>.
`frequency`::
(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`::
(array) An array of index names. Wildcards are supported. For example:
`["it_ops_metrics", "server*"]`.
`job_id`::
(string) A numerical character string that uniquely identifies the job.
`query`::
(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}}`.
`query_delay`::
(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`::
(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 {ref}/search-request-script-fields.html[Script Fields].
`scroll_size`::
(unsigned integer) The `size` parameter that is used in {es} searches.
The default value is `1000`.
`types`::
(array) A list of types to search for within the specified indices.
For example: `["network","sql","kpi"]`.
For more information about these properties,
see <<ml-datafeed-resource>>.
==== Authorization
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
==== Security Integration
When {security} is enabled, your {dfeed} will remember which roles the user who
updated it had at the time of update, and run the query using those same roles.
==== Examples
The following example updates the query for the `datafeed-it-ops-kpi` {dfeed}
so that only log entries of error level are analyzed:
[source,js]
--------------------------------------------------
POST _xpack/ml/datafeeds/datafeed-it-ops-kpi/_update
{
"query": {
"term": {
"level": "error"
}
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:todo]
When the {dfeed} is updated, you receive the full {dfeed} configuration with
with the updated values:
[source,js]
----
{
"datafeed_id": "datafeed-it-ops-kpi",
"job_id": "it-ops-kpi",
"query_delay": "1m",
"indices": ["it-ops"],
"types": ["logs"],
"query": {
"term": {
"level": {
"value": "error",
"boost": 1
}
}
},
"scroll_size": 1000,
"chunking_config": {
"mode": "auto"
}
}
----