put-datafeed.asciidoc 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  1. [role="xpack"]
  2. [[ml-put-datafeed]]
  3. === Create {dfeeds-cap} API
  4. ++++
  5. <titleabbrev>Create {dfeeds-cap}</titleabbrev>
  6. ++++
  7. Instantiates a {dfeed}.
  8. ==== Request
  9. `PUT _xpack/ml/datafeeds/<feed_id>`
  10. ==== Description
  11. You must create a job before you create a {dfeed}. You can associate only one
  12. {dfeed} to each job.
  13. ==== Path Parameters
  14. `feed_id` (required)::
  15. (string) A numerical character string that uniquely identifies the {dfeed}.
  16. ==== Request Body
  17. `aggregations`::
  18. (object) If set, the {dfeed} performs aggregation searches.
  19. For more information, see <<ml-datafeed-resource>>.
  20. `chunking_config`::
  21. (object) Specifies how data searches are split into time chunks.
  22. See <<ml-datafeed-chunking-config>>.
  23. `frequency`::
  24. (time units) The interval at which scheduled queries are made while the {dfeed}
  25. runs in real time. The default value is either the bucket span for short
  26. bucket spans, or, for longer bucket spans, a sensible fraction of the bucket
  27. span. For example: `150s`.
  28. `indices` (required)::
  29. (array) An array of index names. Wildcards are supported. For example:
  30. `["it_ops_metrics", "server*"]`.
  31. `job_id` (required)::
  32. (string) A numerical character string that uniquely identifies the job.
  33. `query`::
  34. (object) The {es} query domain-specific language (DSL). This value
  35. corresponds to the query object in an {es} search POST body. All the
  36. options that are supported by {Es} can be used, as this object is
  37. passed verbatim to {es}. By default, this property has the following
  38. value: `{"match_all": {"boost": 1}}`.
  39. `query_delay`::
  40. (time units) The number of seconds behind real time that data is queried. For
  41. example, if data from 10:04 a.m. might not be searchable in {es} until
  42. 10:06 a.m., set this property to 120 seconds. The default value is `60s`.
  43. `script_fields`::
  44. (object) Specifies scripts that evaluate custom expressions and returns
  45. script fields to the {dfeed}.
  46. The <<ml-detectorconfig,detector configuration objects>> in a job can contain
  47. functions that use these script fields.
  48. For more information,
  49. see {ref}/search-request-script-fields.html[Script Fields].
  50. `scroll_size`::
  51. (unsigned integer) The `size` parameter that is used in {es} searches.
  52. The default value is `1000`.
  53. `types`::
  54. (array) A list of types to search for within the specified indices.
  55. For example: `[]`. This property is provided for backwards compatibility with
  56. releases earlier than 6.0.0. For more information, see <<removal-of-types>>.
  57. For more information about these properties,
  58. see <<ml-datafeed-resource>>.
  59. ==== Authorization
  60. You must have `manage_ml`, or `manage` cluster privileges to use this API.
  61. For more information, see
  62. {xpack-ref}/security-privileges.html[Security Privileges].
  63. ==== Security Integration
  64. When {security} is enabled, your {dfeed} will remember which roles the user who
  65. created it had at the time of creation, and run the query using those same roles.
  66. ==== Examples
  67. The following example creates the `datafeed-total-requests` {dfeed}:
  68. [source,js]
  69. --------------------------------------------------
  70. PUT _xpack/ml/datafeeds/datafeed-total-requests
  71. {
  72. "job_id": "total-requests",
  73. "indices": ["server-metrics"]
  74. }
  75. --------------------------------------------------
  76. // CONSOLE
  77. // TEST[setup:server_metrics_job]
  78. When the {dfeed} is created, you receive the following results:
  79. [source,js]
  80. ----
  81. {
  82. "datafeed_id": "datafeed-total-requests",
  83. "job_id": "total-requests",
  84. "query_delay": "83474ms",
  85. "indices": [
  86. "server-metrics"
  87. ],
  88. "types": [],
  89. "query": {
  90. "match_all": {
  91. "boost": 1.0
  92. }
  93. },
  94. "scroll_size": 1000,
  95. "chunking_config": {
  96. "mode": "auto"
  97. }
  98. }
  99. ----
  100. // TESTRESPONSE[s/"query_delay": "83474ms"/"query_delay": $body.query_delay/]
  101. // TESTRESPONSE[s/"query.boost": "1.0"/"query.boost": $body.query.boost/]