From 6a625ea7510a34632ef2378a800a6db794d98d1b Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 4 Sep 2018 16:26:05 -0700 Subject: [PATCH 1/3] [DOCS] Adds delete forecast API --- .../ml/apis/delete-forecast.asciidoc | 64 +++++++++++++++++++ docs/reference/ml/apis/ml-api.asciidoc | 3 +- 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 docs/reference/ml/apis/delete-forecast.asciidoc diff --git a/docs/reference/ml/apis/delete-forecast.asciidoc b/docs/reference/ml/apis/delete-forecast.asciidoc new file mode 100644 index 0000000000000..be5667d1c03ce --- /dev/null +++ b/docs/reference/ml/apis/delete-forecast.asciidoc @@ -0,0 +1,64 @@ +[role="xpack"] +[testenv="platinum"] +[[ml-delete-forecast]] +=== Delete Forecast API +++++ +Delete Forecast +++++ + +Deletes forecasts from a {ml} job. + +==== Request + +`DELETE _xpack/ml/anomaly_detectors//_forecast` + + +`DELETE _xpack/ml/anomaly_detectors//_forecast/` + + +`DELETE _xpack/ml/anomaly_detectors//_forecast/_all` + + +==== Description + +By default, forecasts are retained for 14 days. You can specify a different +retention period with the `expires_in` parameter in the <>. The delete forecast API enables you to delete one or more forecasts before they expire. + +NOTE: When you delete a job its associated forecasts are deleted. + +For more information, see {xpack-ref}/ml-overview.html#ml-forecasting[Forecasting the Future]. + + +==== Path Parameters + +`job_id` (required):: + (string) Identifier for the job. + +`forecast_id`:: + (string) A comma-separated list of forecast identifiers. +//TBD: Can this ID be retrieved somehow? + If you do not specify this optional parameter or if you specify `_all`, the + API deletes all forecasts from the job. + +==== Request Parameters + +`allow_no_forecasts`:: + (boolean) Whether to ignore if `_all` matches no forecasts. +//TBD: This description is unclear. Does this mean that if this parameter is +//false and there are no forecasts in the job, an error is returned? + +`timeout`:: + (time units) Controls the time to wait until the forecasts are deleted. + Defaults to 30 seconds. For more information about time units, see <>. +//TBD: This description is unclear. Is it the time to wait until the deletion +//is initiated? Or is it the time to wait for the deletion to complete? If the +//latter, I presume an error is returned and you must try again. + + +//==== 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]. +//// + +// ==== Examples + diff --git a/docs/reference/ml/apis/ml-api.asciidoc b/docs/reference/ml/apis/ml-api.asciidoc index b8509f221524c..961eb37e9d7e0 100644 --- a/docs/reference/ml/apis/ml-api.asciidoc +++ b/docs/reference/ml/apis/ml-api.asciidoc @@ -48,7 +48,7 @@ machine learning APIs and in advanced job configuration options in Kibana. * <> * <> * <> -* <> +* <>, <> [float] [[ml-api-snapshot-endpoint]] @@ -85,6 +85,7 @@ include::delete-calendar.asciidoc[] include::delete-datafeed.asciidoc[] include::delete-calendar-event.asciidoc[] include::delete-filter.asciidoc[] +include::delete-forecast.asciidoc[] include::delete-job.asciidoc[] include::delete-calendar-job.asciidoc[] include::delete-snapshot.asciidoc[] From 6bc7a02ac21c474d88e9fd6bd5aa468b600aeae6 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 5 Sep 2018 14:53:43 -0700 Subject: [PATCH 2/3] [DOCS] Adds delete forecast example --- .../ml/apis/delete-forecast.asciidoc | 51 ++++++++++++------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/docs/reference/ml/apis/delete-forecast.asciidoc b/docs/reference/ml/apis/delete-forecast.asciidoc index be5667d1c03ce..a96cce1c8776a 100644 --- a/docs/reference/ml/apis/delete-forecast.asciidoc +++ b/docs/reference/ml/apis/delete-forecast.asciidoc @@ -24,7 +24,7 @@ retention period with the `expires_in` parameter in the <>. -//TBD: This description is unclear. Is it the time to wait until the deletion -//is initiated? Or is it the time to wait for the deletion to complete? If the -//latter, I presume an error is returned and you must try again. + (time units) Specifies the period of time to wait for the completion of the + delete operation. When this period of time elapses, the API fails and returns + an error. The default value is `30s`. For more information about time units, + see <>. -//==== Authorization +==== 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]. -//// - -// ==== Examples - +For more information, see {stack-ov}/security-privileges.html[Security Privileges]. + +==== Examples + +The following example deletes all forecasts from the `total-requests` job: + +[source,js] +-------------------------------------------------- +DELETE _xpack/ml/anomaly_detectors/total-requests/_forecast/wkCWa2IB2lF8nSE_TzZo +-------------------------------------------------- +// CONSOLE +// TEST[setup:server_metrics_openjob] +// TEST[catch:missing] + +If the request does not encounter errors, you receive the following result: +[source,js] +---- +{ + "acknowledged": true +} +---- +// NOTCONSOLE From c8423aeffda92fe1fc1d5c79074ea6e0f7bd9fb5 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 5 Sep 2018 16:55:11 -0700 Subject: [PATCH 3/3] [DOCS] Disables example testing --- docs/reference/ml/apis/delete-forecast.asciidoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/reference/ml/apis/delete-forecast.asciidoc b/docs/reference/ml/apis/delete-forecast.asciidoc index a96cce1c8776a..159dafefb0efc 100644 --- a/docs/reference/ml/apis/delete-forecast.asciidoc +++ b/docs/reference/ml/apis/delete-forecast.asciidoc @@ -63,11 +63,10 @@ The following example deletes all forecasts from the `total-requests` job: [source,js] -------------------------------------------------- -DELETE _xpack/ml/anomaly_detectors/total-requests/_forecast/wkCWa2IB2lF8nSE_TzZo +DELETE _xpack/ml/anomaly_detectors/total-requests/_forecast/_all -------------------------------------------------- // CONSOLE -// TEST[setup:server_metrics_openjob] -// TEST[catch:missing] +// TEST[skip:setup:server_metrics_openjob] If the request does not encounter errors, you receive the following result: [source,js]