put-datafeed.asciidoc 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146
  1. [role="xpack"]
  2. [testenv="platinum"]
  3. [[ml-put-datafeed]]
  4. === Create {dfeeds} API
  5. [subs="attributes"]
  6. ++++
  7. <titleabbrev>Create {dfeeds}</titleabbrev>
  8. ++++
  9. Instantiates a {dfeed}.
  10. [[ml-put-datafeed-request]]
  11. ==== {api-request-title}
  12. `PUT _ml/datafeeds/<feed_id>`
  13. [[ml-put-datafeed-prereqs]]
  14. ==== {api-prereq-title}
  15. * You must create an {anomaly-job} before you create a {dfeed}.
  16. * If {es} {security-features} are enabled, you must have `manage_ml` or `manage`
  17. cluster privileges to use this API. See
  18. <<security-privileges>>.
  19. [[ml-put-datafeed-desc]]
  20. ==== {api-description-title}
  21. {ml-docs}/ml-dfeeds.html[{dfeeds-cap}] retrieve data from {es} for analysis by
  22. an {anomaly-job}. You can associate only one {dfeed} to each {anomaly-job}.
  23. The {dfeed} contains a query that runs at a defined interval (`frequency`). If
  24. you are concerned about delayed data, you can add a delay (`query_delay`) at
  25. each interval. See {ml-docs}/ml-delayed-data-detection.html[Handling delayed data].
  26. [IMPORTANT]
  27. ====
  28. * You must use {kib} or this API to create a {dfeed}. Do not put a
  29. {dfeed} directly to the `.ml-config` index using the {es} index API. If {es}
  30. {security-features} are enabled, do not give users `write` privileges on the
  31. `.ml-config` index.
  32. * When {es} {security-features} are enabled, your {dfeed} remembers which roles
  33. the user who created it had at the time of creation and runs the query using
  34. those same roles.
  35. * It is possible that secondary authorization headers are supplied in the
  36. request. If this is the case, the secondary authorization headers are used
  37. instead of the primary headers.
  38. ====
  39. [[ml-put-datafeed-path-parms]]
  40. ==== {api-path-parms-title}
  41. `<feed_id>`::
  42. (Required, string)
  43. include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
  44. [role="child_attributes"]
  45. [[ml-put-datafeed-request-body]]
  46. ==== {api-request-body-title}
  47. `aggregations`::
  48. (Optional, object)
  49. include::{docdir}/ml/ml-shared.asciidoc[tag=aggregations]
  50. `chunking_config`::
  51. (Optional, object)
  52. include::{docdir}/ml/ml-shared.asciidoc[tag=chunking-config]
  53. `delayed_data_check_config`::
  54. (Optional, object)
  55. include::{docdir}/ml/ml-shared.asciidoc[tag=delayed-data-check-config]
  56. `frequency`::
  57. (Optional, <<time-units, time units>>)
  58. include::{docdir}/ml/ml-shared.asciidoc[tag=frequency]
  59. `indices`::
  60. (Required, array)
  61. include::{docdir}/ml/ml-shared.asciidoc[tag=indices]
  62. `job_id`::
  63. (Required, string)
  64. include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
  65. `max_empty_searches`::
  66. (Optional,integer)
  67. include::{docdir}/ml/ml-shared.asciidoc[tag=max-empty-searches]
  68. `query`::
  69. (Optional, object)
  70. include::{docdir}/ml/ml-shared.asciidoc[tag=query]
  71. `query_delay`::
  72. (Optional, <<time-units, time units>>)
  73. include::{docdir}/ml/ml-shared.asciidoc[tag=query-delay]
  74. `script_fields`::
  75. (Optional, object)
  76. include::{docdir}/ml/ml-shared.asciidoc[tag=script-fields]
  77. `scroll_size`::
  78. (Optional, unsigned integer)
  79. include::{docdir}/ml/ml-shared.asciidoc[tag=scroll-size]
  80. `indices_options`::
  81. (Optional, object)
  82. include::{docdir}/ml/ml-shared.asciidoc[tag=indices-options]
  83. [[ml-put-datafeed-example]]
  84. ==== {api-examples-title}
  85. [source,console]
  86. --------------------------------------------------
  87. PUT _ml/datafeeds/datafeed-total-requests
  88. {
  89. "job_id": "total-requests",
  90. "indices": ["server-metrics"]
  91. }
  92. --------------------------------------------------
  93. // TEST[skip:setup:server_metrics_job]
  94. When the {dfeed} is created, you receive the following results:
  95. [source,console-result]
  96. ----
  97. {
  98. "datafeed_id": "datafeed-total-requests",
  99. "job_id": "total-requests",
  100. "query_delay": "83474ms",
  101. "indices": [
  102. "server-metrics"
  103. ],
  104. "query": {
  105. "match_all": {
  106. "boost": 1.0
  107. }
  108. },
  109. "scroll_size": 1000,
  110. "chunking_config": {
  111. "mode": "auto"
  112. }
  113. }
  114. ----
  115. // TESTRESPONSE[s/"query_delay": "83474ms"/"query_delay": $body.query_delay/]
  116. // TESTRESPONSE[s/"query.boost": "1.0"/"query.boost": $body.query.boost/]