[role="xpack"]
[[ml-put-datafeed]]
= Create {dfeeds} API

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

Instantiates a {dfeed}.

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

`PUT _ml/datafeeds/<feed_id>`

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

* You must create an {anomaly-job} before you create a {dfeed}.
* Requires the following privileges:
** cluster: `manage_ml` (the `machine_learning_admin` built-in role grants this 
  privilege)
** source index configured in the {dfeed}: `read`

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

{ml-docs}/ml-ad-run-jobs.html#ml-ad-datafeeds[{dfeeds-cap}] retrieve data from 
{es} for analysis by an {anomaly-job}. You can associate only one {dfeed} to 
each {anomaly-job}.

The {dfeed} contains a query that runs at a defined interval (`frequency`). If
you are concerned about delayed data, you can add a delay (`query_delay`) at
each interval. See {ml-docs}/ml-delayed-data-detection.html[Handling delayed data].

[IMPORTANT]
====
* You must use {kib}, this API, or the <<ml-put-job,create {anomaly-jobs} API>>
to create a {dfeed}. Do not add a {dfeed} directly to the `.ml-config` index
using the {es} index API. If {es} {security-features} are enabled, do not give
users `write` privileges on the `.ml-config` index.
* When {es} {security-features} are enabled, your {dfeed} remembers which roles
the user who created it had at the time of creation and runs the query using
those same roles. If you provide
<<http-clients-secondary-authorization,secondary authorization headers>>, those
credentials are used instead.
====

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

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

[[ml-put-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-put-datafeed-request-body]]
== {api-request-body-title}

`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`::
(Required, 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]

`job_id`::
(Required, string)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]

`max_empty_searches`::
(Optional,integer)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=max-empty-searches]

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

`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-put-datafeed-example]]
== {api-examples-title}

Create a {dfeed} for an {anomaly-job} (`test-job`):

[source,console]
--------------------------------------------------
PUT _ml/datafeeds/datafeed-test-job?pretty
{
  "indices": [
    "kibana_sample_data_logs"
  ],
  "query": {
    "bool": {
      "must": [
        {
          "match_all": {}
        }
      ]
    }
  },
  "job_id": "test-job"
}
--------------------------------------------------
// TEST[skip:setup ecommerce job]

When the {dfeed} is created, you receive the following results:

[source,console-result]
----
{
  "datafeed_id" : "datafeed-test-job",
  "job_id" : "test-job",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "query_delay" : "91820ms",
  "chunking_config" : {
    "mode" : "auto"
  },
  "indices_options" : {
    "expand_wildcards" : [
      "open"
    ],
    "ignore_unavailable" : false,
    "allow_no_indices" : true,
    "ignore_throttled" : true
  },
  "query" : {
    "bool" : {
      "must" : [
        {
          "match_all" : { }
        }
      ]
    }
  },
  "indices" : [
    "kibana_sample_data_logs"
  ],
  "scroll_size" : 1000,
  "delayed_data_check_config" : {
    "enabled" : true
  }
}
----
// TESTRESPONSE[s/"query_delay": "91820ms"/"query_delay": $body.query_delay/]