start-datafeed.asciidoc 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. [role="xpack"]
  2. [[ml-start-datafeed]]
  3. = Start {dfeeds} API
  4. [subs="attributes"]
  5. ++++
  6. <titleabbrev>Start {dfeeds}</titleabbrev>
  7. ++++
  8. Starts one or more {dfeeds}.
  9. [[ml-start-datafeed-request]]
  10. == {api-request-title}
  11. `POST _ml/datafeeds/<feed_id>/_start`
  12. [[ml-start-datafeed-prereqs]]
  13. == {api-prereq-title}
  14. * Before you can start a {dfeed}, the {anomaly-job} must be open. Otherwise, an
  15. error occurs.
  16. * Requires the `manage_ml` cluster privilege. This privilege is included in the
  17. `machine_learning_admin` built-in role.
  18. [[ml-start-datafeed-desc]]
  19. == {api-description-title}
  20. A {dfeed} must be started in order to retrieve data from {es}.
  21. A {dfeed} can be started and stopped multiple times throughout its lifecycle.
  22. If you restart a stopped {dfeed}, by default it continues processing input data
  23. from the next millisecond after it was stopped. If new data was indexed for that
  24. exact millisecond between stopping and starting, it will be ignored.
  25. IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
  26. which roles the last user to create or update it had at the time of
  27. creation/update and runs the query using those same roles. If you provided
  28. <<http-clients-secondary-authorization,secondary authorization headers>> when
  29. you created or updated the {dfeed}, those credentials are used instead.
  30. [[ml-start-datafeed-path-parms]]
  31. == {api-path-parms-title}
  32. `<feed_id>`::
  33. (Required, string)
  34. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=datafeed-id]
  35. [[ml-start-datafeed-query-parms]]
  36. == {api-query-parms-title}
  37. `end`::
  38. (Optional, string) The time that the {dfeed} should end, which can be
  39. specified by using one of the following formats:
  40. +
  41. --
  42. * ISO 8601 format with milliseconds, for example `2017-01-22T06:00:00.000Z`
  43. * ISO 8601 format without milliseconds, for example `2017-01-22T06:00:00+00:00`
  44. * Milliseconds since the epoch, for example `1485061200000`
  45. Date-time arguments using either of the ISO 8601 formats must have a time zone
  46. designator, where `Z` is accepted as an abbreviation for UTC time.
  47. NOTE: When a URL is expected (for example, in browsers), the `+` used in time
  48. zone designators must be encoded as `%2B`.
  49. This value is exclusive. If you do not specify an end time, the {dfeed} runs
  50. continuously.
  51. --
  52. `start`::
  53. (Optional, string) The time that the {dfeed} should begin, which can be
  54. specified by using the same formats as the `end` parameter. This value is
  55. inclusive.
  56. +
  57. If you do not specify a start time and the {dfeed} is associated with a new
  58. {anomaly-job}, the analysis starts from the earliest time for which data is
  59. available.
  60. +
  61. If you restart a stopped {dfeed} and specify a `start` value that is earlier
  62. than the timestamp of the latest processed record, the {dfeed} continues from
  63. 1 millisecond after the timestamp of the latest processed record.
  64. `timeout`::
  65. (Optional, time) Specifies the amount of time to wait until a {dfeed} starts.
  66. The default value is 20 seconds.
  67. [[ml-start-datafeed-request-body]]
  68. == {api-request-body-title}
  69. You can also specify the query parameters (such as `end` and `start`)
  70. in the request body.
  71. [[ml-start-datafeed-response-body]]
  72. == {api-response-body-title}
  73. `node`::
  74. (string) The ID of the node that the {dfeed} was started on. If the {dfeed} is
  75. allowed to open lazily and has not yet been assigned to a node, this value is
  76. an empty string.
  77. `started`::
  78. (Boolean) For a successful response, this value is always `true`. On failure, an
  79. exception is returned instead.
  80. [[ml-start-datafeed-example]]
  81. == {api-examples-title}
  82. [source,console]
  83. --------------------------------------------------
  84. POST _ml/datafeeds/datafeed-low_request_rate/_start
  85. {
  86. "start": "2019-04-07T18:22:16Z"
  87. }
  88. --------------------------------------------------
  89. // TEST[skip:Kibana sample data]
  90. When the {dfeed} starts, you receive the following results:
  91. [source,console-result]
  92. ----
  93. {
  94. "started" : true,
  95. "node" : "node-1"
  96. }
  97. ----