honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Adds anchors and attributes to ML APIs

This commit is contained in:
lcawl 2019-06-27 09:42:47 -07:00
parent 6744344ef2
commit d46e2bb26a
52 changed files with 585 additions and 528 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/data-frames/apis/delete-transform.asciidoc
View File

@ -43,7 +43,7 @@ NOTE: Before you can delete the {dataframe-transform}, you must stop it.
[discrete]
[[delete-data-frame-transform-examples]]
==== {api-example-title}
==== {api-examples-title}
[source,js]
--------------------------------------------------

2
docs/reference/data-frames/apis/get-transform.asciidoc
View File

@ -73,7 +73,7 @@ see {stack-ov}/security-privileges.html[Security privileges] and
[discrete]
[[get-data-frame-transform-example]]
==== {api-example-title}
==== {api-examples-title}
The following example retrieves information about a maximum of ten transforms:

2
docs/reference/data-frames/apis/preview-transform.asciidoc
View File

@ -42,7 +42,7 @@ If the {es} {security-features} are enabled, you must have
reduce the data. See <<data-frame-transform-pivot>>.
[discrete]
==== {api-example-title}
==== {api-examples-title}
[source,js]
--------------------------------------------------

2
docs/reference/data-frames/apis/put-transform.asciidoc
View File

@ -71,7 +71,7 @@ IMPORTANT: You must use {kib} or this API to create a {dataframe-transform}.
[discrete]
[[put-data-frame-transform-example]]
==== {api-example-title}
==== {api-examples-title}
[source,js]
--------------------------------------------------

2
docs/reference/data-frames/apis/start-transform.asciidoc
View File

@ -40,7 +40,7 @@ have `view_index_metadata` privileges on the source index for the
[discrete]
[[start-data-frame-transform-example]]
==== {api-example-title}
==== {api-examples-title}
[source,js]
--------------------------------------------------

2
docs/reference/data-frames/apis/stop-transform.asciidoc
View File

@ -74,7 +74,7 @@ All {dataframe-transforms} can be stopped by using `_all` or `*` as the
[discrete]
[[stop-data-frame-transform-example]]
==== {api-example-title}
==== {api-examples-title}
[source,js]
--------------------------------------------------

28
docs/reference/ml/apis/close-job.asciidoc
View File

@ -12,8 +12,9 @@ A job can be opened and closed multiple times throughout its lifecycle.
A closed job cannot receive data or perform analysis
operations, but you can still explore and navigate results.
==== Request
[discrete]
[[ml-close-job-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/_close` +
@ -21,8 +22,8 @@ operations, but you can still explore and navigate results.
`POST _ml/anomaly_detectors/_all/_close` +
==== Description
[[ml-close-job-desc]]
==== {api-description-title}
You can close multiple jobs in a single API request by using a group name, a
comma-separated list of jobs, or a wildcard expression. You can close all jobs
@ -47,15 +48,16 @@ after the close job API returns. The `force` query parameter should only be use
situations where the job has already failed, or where you are not interested in
results the job might have recently produced or might produce in the future.
==== Path Parameters
[discrete]
[[ml-close-job-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job. It can be a job identifier, a group name, or
a wildcard expression.
==== Query Parameters
[[ml-close-job-query-parms]]
==== {api-query-parms-title}
`force`::
(boolean) Use to close a failed job, or to forcefully close a job which has not
@ -65,14 +67,14 @@ results the job might have recently produced or might produce in the future.
(time units) Controls the time to wait until a job has closed.
The default value is 30 minutes.
==== Authorization
[[ml-close-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
For more information, see {stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-close-job-example]]
==== {api-examples-title}
The following example closes the `total-requests` job:

20
docs/reference/ml/apis/delete-calendar-event.asciidoc
View File

@ -8,19 +8,20 @@
Deletes scheduled events from a calendar.
==== Request
[[ml-delete-calendar-event-request]]
==== {api-request-title}
`DELETE _ml/calendars/<calendar_id>/events/<event_id>`
==== Description
[[ml-delete-calendar-event-desc]]
==== {api-description-title}
This API removes individual events from a calendar. To remove all scheduled
events and delete the calendar, see the
<<ml-delete-calendar,delete calendar API>>.
==== Path Parameters
[[ml-delete-calendar-event-path-parms]]
==== {api-path-parms-title}
`calendar_id`(required)::
(string) Identifier for the calendar.
@ -29,13 +30,14 @@ events and delete the calendar, see the
(string) Identifier for the scheduled event. You can obtain this identifier
by using the <<ml-get-calendar-event,get calendar events API>>.
==== Authorization
[[ml-delete-calendar-event-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
For more information, see {stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-delete-calendar-event-example]]
==== {api-examples-title}
The following example deletes a scheduled event from the `planned-outages`
calendar:

17
docs/reference/ml/apis/delete-calendar-job.asciidoc
View File

@ -8,13 +8,13 @@
Deletes jobs from a calendar.
==== Request
[[ml-delete-calendar-job-request]]
==== {api-request-title}
`DELETE _ml/calendars/<calendar_id>/jobs/<job_id>`
==== Path Parameters
[[ml-delete-calendar-job-path-parms]]
==== {api-path-parms-title}
`calendar_id`(required)::
(string) Identifier for the calendar.
@ -23,13 +23,14 @@ Deletes jobs from a calendar.
(string) An identifier for the job. It can be a job identifier, a group name, or a
comma-separated list of jobs or groups.
==== Authorization
[[ml-delete-calendar-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
For more information, see {stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-delete-calendar-job-example]]
==== {api-examples-title}
The following example removes the association between the `planned-outages`
calendar and `total-requests` job:

22
docs/reference/ml/apis/delete-calendar.asciidoc
View File

@ -8,31 +8,31 @@
Deletes a calendar.
==== Request
[[ml-delete-calendar-request]]
==== {api-request-title}
`DELETE _ml/calendars/<calendar_id>`
==== Description
[[ml-delete-calendar-desc]]
==== {api-description-title}
This API removes all scheduled events from the calendar then deletes the
calendar.
==== Path Parameters
[[ml-delete-calendar-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
(string) Identifier for the calendar.
==== Authorization
[[ml-delete-calendar-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
For more information, see {stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-delete-calendar-example]]
==== {api-examples-title}
The following example deletes the `planned-outages` calendar:

27
docs/reference/ml/apis/delete-datafeed.asciidoc
View File

@ -10,38 +10,37 @@
Deletes an existing {dfeed}.
==== Request
[[ml-delete-datafeed-request]]
==== {api-request-title}
`DELETE _ml/datafeeds/<feed_id>`
==== Description
[[ml-delete-datafeed-desc]]
==== {api-description-title}
NOTE: Unless the `force` parameter is used, the {dfeed} must be stopped before it can be deleted.
==== Path Parameters
[[ml-delete-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) Identifier for the {dfeed}
===== Query Parameters
[[ml-delete-datafeed-query-parms]]
==== {api-query-parms-title}
`force`::
(boolean) Use to forcefully delete a started {dfeed}; this method is quicker than
stopping and deleting the {dfeed}.
===== Authorization
[[ml-delete-datafeed-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
For more information, see {stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-delete-datafeed-example]]
==== {api-examples-title}
The following example deletes the `datafeed-total-requests` {dfeed}:

13
docs/reference/ml/apis/delete-expired-data.asciidoc
View File

@ -8,25 +8,28 @@
Deletes expired and unused machine learning data.
==== Request
[[ml-delete-expired-data-request]]
==== {api-request-title}
`DELETE _ml/_delete_expired_data`
==== Description
[[ml-delete-expired-data-desc]]
==== {api-description-title}
Deletes all job results, model snapshots and forecast data that have exceeded
their `retention days` period. Machine learning state documents that are not
associated with any job are also deleted.
==== Authorization
[[ml-delete-expired-data-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
==== Examples
[[ml-delete-expired-data-example]]
==== {api-examples-title}
The endpoint takes no arguments:

20
docs/reference/ml/apis/delete-filter.asciidoc
View File

@ -8,32 +8,32 @@
Deletes a filter.
==== Request
[[ml-delete-filter-request]]
==== {api-request-title}
`DELETE _ml/filters/<filter_id>`
==== Description
[[ml-delete-filter-desc]]
==== {api-description-title}
This API deletes a {stack-ov}/ml-rules.html[filter].
If a {ml} job references the filter, you cannot delete the filter. You must
update or delete the job before you can delete the filter.
==== Path Parameters
[[ml-delete-filter-path-parms]]
==== {api-path-parms-title}
`filter_id` (required)::
(string) Identifier for the filter.
==== Authorization
[[ml-delete-filter-prereqs]]
==== {api-prereq-title}
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
[[ml-delete-filter-example]]
==== {api-examples-title}
The following example deletes the `safe_domains` filter:

21
docs/reference/ml/apis/delete-forecast.asciidoc
View File

@ -8,7 +8,8 @@
Deletes forecasts from a {ml} job.
==== Request
[[ml-delete-forecast-request]]
==== {api-request-title}
`DELETE _ml/anomaly_detectors/<job_id>/_forecast` +
@ -16,8 +17,8 @@ Deletes forecasts from a {ml} job.
`DELETE _ml/anomaly_detectors/<job_id>/_forecast/_all`
==== Description
[[ml-delete-forecast-desc]]
==== {api-description-title}
By default, forecasts are retained for 14 days. You can specify a different
retention period with the `expires_in` parameter in the <<ml-forecast,forecast jobs API>>. The delete forecast API enables you to delete one or more forecasts before they expire.
@ -26,8 +27,8 @@ NOTE: When you delete a job its associated forecasts are deleted.
For more information, see {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the Future].
==== Path Parameters
[[ml-delete-forecast-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job.
@ -37,7 +38,8 @@ For more information, see {stack-ov}/ml-overview.html#ml-forecasting[Forecasting
If you do not specify this optional parameter or if you specify `_all`, the
API deletes all forecasts from the job.
==== Request Parameters
[[ml-delete-forecast-request-body]]
==== {api-request-body-title}
`allow_no_forecasts`::
(boolean) Specifies whether an error occurs when there are no forecasts. In
@ -51,13 +53,14 @@ For more information, see {stack-ov}/ml-overview.html#ml-forecasting[Forecasting
an error. The default value is `30s`. For more information about time units,
see <<time-units>>.
==== Authorization
[[ml-delete-forecast-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-delete-forecast-example]]
==== {api-examples-title}
The following example deletes all forecasts from the `total-requests` job:

21
docs/reference/ml/apis/delete-job.asciidoc
View File

@ -8,13 +8,13 @@
Deletes an existing anomaly detection job.
==== Request
[[ml-delete-job-request]]
==== {api-request-title}
`DELETE _ml/anomaly_detectors/<job_id>`
==== Description
[[ml-delete-job-desc]]
==== {api-description-title}
All job configuration, model state and results are deleted.
@ -30,12 +30,14 @@ is used the job must be closed before it can be deleted.
It is not currently possible to delete multiple jobs using wildcards or a comma
separated list.
==== Path Parameters
[[ml-delete-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
===== Query Parameters
[[ml-delete-job-query-parms]]
==== {api-query-parms-title}
`force`::
(boolean) Use to forcefully delete an opened job; this method is quicker than
@ -45,14 +47,15 @@ separated list.
(boolean) Specifies whether the request should return immediately or wait
until the job deletion completes. Defaults to `true`.
==== Authorization
[[ml-delete-job-prereqs]]
==== {api-prereq-title}
If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
cluster privileges to use this API.
For more information, see {stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-delete-job-example]]
==== {api-examples-title}
The following example deletes the `total-requests` job:

19
docs/reference/ml/apis/delete-snapshot.asciidoc
View File

@ -8,19 +8,20 @@
Deletes an existing model snapshot.
==== Request
[[ml-delete-snapshot-request]]
==== {api-request-title}
`DELETE _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
==== Description
[[ml-delete-snapshot-desc]]
==== {api-description-title}
IMPORTANT: You cannot delete the active model snapshot. To delete that snapshot,
first revert to a different one. To identify the active model snapshot, refer to
the `model_snapshot_id` in the results from the get jobs API.
==== Path Parameters
[[ml-delete-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
@ -28,14 +29,14 @@ the `model_snapshot_id` in the results from the get jobs API.
`snapshot_id` (required)::
(string) Identifier for the model snapshot
==== Authorization
[[ml-delete-snapshot-prereqs]]
==== {api-prereq-title}
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
[[ml-delete-snapshot-example]]
==== {api-examples-title}
The following example deletes the `1491948163` snapshot:

19
docs/reference/ml/apis/find-file-structure.asciidoc
View File

@ -11,12 +11,13 @@ experimental[]
Finds the structure of a text file. The text file must contain data that is
suitable to be ingested into {es}.
==== Request
[[ml-find-file-structure-request]]
==== {api-request-title}
`POST _ml/find_file_structure`
==== Description
[[ml-find-file-structure-desc]]
==== {api-description-title}
This API provides a starting point for ingesting data into {es} in a format that
is suitable for subsequent use with other {ml} functionality.
@ -47,7 +48,8 @@ specify the `explain` query parameter. It causes an `explanation` to appear in
the response, which should help in determining why the returned structure was
chosen.
==== Query Parameters
[[ml-find-file-structure-query-parms]]
==== {api-query-parms-title}
`charset`::
(string) The file's character set. It must be a character set that is supported
@ -197,22 +199,23 @@ format from a built-in set.
--
==== Request Body
[[ml-find-file-structure-request-body]]
==== {api-request-body-title}
The text file that you want to analyze. It must contain data that is suitable to
be ingested into {es}. It does not need to be in JSON format and it does not
need to be UTF-8 encoded. The size is limited to the {es} HTTP receive buffer
size, which defaults to 100 Mb.
==== Authorization
[[ml-find-file-structure-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, or `monitor` cluster privileges to use this API.
For more information, see {stack-ov}/security-privileges.html[Security Privileges].
[[ml-find-file-structure-examples]]
==== Examples
==== {api-examples-title}
Suppose you have a newline-delimited JSON file that contains information about
some books. You can send the contents to the `find_file_structure` endpoint:

24
docs/reference/ml/apis/flush-job.asciidoc
View File

@ -8,13 +8,13 @@
Forces any buffered data to be processed by the job.
==== Request
[[ml-flush-job-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/_flush`
==== Description
[[ml-flush-job-desc]]
==== {api-description-title}
The flush jobs API is only applicable when sending data for analysis using the
<<ml-post-data,post data API>>. Depending on the content of the buffer, then it
@ -26,14 +26,14 @@ remains open and is available to continue analyzing data. A close operation
additionally prunes and persists the model state to disk and the job must be
opened again before analyzing further data.
==== Path Parameters
[[ml-flush-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
==== Query Parameters
[[ml-flush-job-query-parms]]
==== {api-query-parms-title}
`advance_time`::
(string) Specifies to advance to a particular time value. Results are
@ -56,14 +56,14 @@ opened again before analyzing further data.
(string) When used in conjunction with `calc_interim`, specifies the range of
buckets on which to calculate interim results.
==== Authorization
[[ml-flush-job-prereqs]]
==== {api-prereq-title}
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
[[ml-flush-job-example]]
==== {api-examples-title}
The following example flushes the `total-requests` job:

23
docs/reference/ml/apis/forecast.asciidoc
View File

@ -8,14 +8,15 @@
Predicts the future behavior of a time series by using its historical behavior.
==== Request
[[ml-forecast-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/_forecast`
[[ml-forecast-desc]]
==== {api-description-title}
==== Description
See {xpack-ref}/ml-overview.html#ml-forecasting[Forecasting the Future].
See {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the Future].
[NOTE]
===============================
@ -25,13 +26,14 @@ forecast. For more information about this property, see <<ml-job-resource>>.
* The job must be open when you create a forecast. Otherwise, an error occurs.
===============================
==== Path Parameters
[[ml-forecast-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job.
==== Request Parameters
[[ml-forecast-request-body]]
==== {api-request-body-title}
`duration`::
(time units) A period of time that indicates how far into the future to
@ -45,13 +47,14 @@ forecast. For more information about this property, see <<ml-job-resource>>.
If set to a value of `0`, the forecast is never automatically deleted.
For more information about time units, see <<time-units>>.
==== Authorization
[[ml-forecast-prereqs]]
==== {api-prereq-title}
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
[[ml-forecast-example]]
==== {api-examples-title}
The following example requests a 10 day forecast for the `total-requests` job:

32
docs/reference/ml/apis/get-bucket.asciidoc
View File

@ -8,21 +8,21 @@
Retrieves job results for one or more buckets.
==== Request
[[ml-get-bucket-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/results/buckets` +
`GET _ml/anomaly_detectors/<job_id>/results/buckets/<timestamp>`
==== Description
[[ml-get-bucket-desc]]
==== {api-description-title}
The get buckets API presents a chronological view of the records, grouped by
bucket.
==== Path Parameters
[[ml-get-bucket-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job
@ -32,8 +32,8 @@ bucket.
If you do not specify this optional parameter, the API returns information
about all buckets.
==== Request Body
[[ml-get-bucket-request-body]]
==== {api-request-body-title}
`anomaly_score`::
(double) Returns buckets with anomaly scores greater or equal than this value.
@ -64,8 +64,8 @@ bucket.
`start`::
(string) Returns buckets with timestamps after this time.
===== Results
[[ml-get-bucket-results]]
==== {api-response-body-title}
The API returns the following information:
@ -73,18 +73,18 @@ The API returns the following information:
(array) An array of bucket objects. For more information, see
<<ml-results-buckets,Buckets>>.
==== Authorization
[[ml-get-bucket-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. You also need `read` index privilege on the index
that stores the results. The `machine_learning_admin` and `machine_learning_user`
roles provide these privileges. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges] and
{xpack-ref}/built-in-roles.html[Built-in Roles].
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
==== Examples
[[ml-get-bucket-example]]
==== {api-examples-title}
The following example gets bucket information for the `it-ops-kpi` job:

27
docs/reference/ml/apis/get-calendar-event.asciidoc
View File

@ -9,25 +9,27 @@
Retrieves information about the scheduled events in
calendars.
==== Request
[[ml-get-calendar-event-request]]
==== {api-request-title}
`GET _ml/calendars/<calendar_id>/events` +
`GET _ml/calendars/_all/events`
===== Description
[[ml-get-calendar-event-desc]]
==== {api-description-title}
You can get scheduled event information for a single calendar or for all
calendars by using `_all`.
==== Path Parameters
[[ml-get-calendar-event-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
(string) Identifier for the calendar.
==== Request Body
[[ml-get-calendar-event-request-body]]
==== {api-request-body-title}
`end`::
(string) Specifies to get events with timestamps earlier than this time.
@ -41,7 +43,8 @@ calendars by using `_all`.
`start`::
(string) Specifies to get events with timestamps after this time.
==== Results
[[ml-get-calendar-event-results]]
==== {api-response-body-title}
The API returns the following information:
@ -49,15 +52,15 @@ The API returns the following information:
(array) An array of scheduled event resources.
For more information, see <<ml-event-resource>>.
==== Authorization
[[ml-get-calendar-event-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-calendar-event-example]]
==== {api-examples-title}
The following example gets information about the scheduled events in the
`planned-outages` calendar:

30
docs/reference/ml/apis/get-calendar.asciidoc
View File

@ -8,27 +8,27 @@
Retrieves configuration information for calendars.
==== Request
[[ml-get-calendar-request]]
==== {api-request-title}
`GET _ml/calendars/<calendar_id>` +
`GET _ml/calendars/_all`
===== Description
[[ml-get-calendar-desc]]
==== {api-description-title}
You can get information for a single calendar or for all calendars by using
`_all`.
==== Path Parameters
[[ml-get-calendar-path-parms]]
==== {api-path-parms-title}
`calendar_id`::
(string) Identifier for the calendar.
==== Request Body
[[ml-get-calendar-request-body]]
==== {api-request-body-title}
`page`::
`from`:::
@ -37,8 +37,8 @@ You can get information for a single calendar or for all calendars by using
`size`:::
(integer) Specifies the maximum number of calendars to obtain.
==== Results
[[ml-get-calendar-results]]
==== {api-response-body-title}
The API returns the following information:
@ -46,15 +46,15 @@ The API returns the following information:
(array) An array of calendar resources.
For more information, see <<ml-calendar-resource>>.
==== Authorization
[[ml-get-calendar-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-calendar-example]]
==== {api-examples-title}
The following example gets configuration information for the `planned-outages`
calendar:

32
docs/reference/ml/apis/get-category.asciidoc
View File

@ -8,19 +8,21 @@
Retrieves job results for one or more categories.
==== Request
[[ml-get-category-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/results/categories` +
`GET _ml/anomaly_detectors/<job_id>/results/categories/<category_id>`
==== Description
[[ml-get-category-desc]]
==== {api-description-title}
For more information about categories, see
{xpack-ref}/ml-configuring-categories.html[Categorizing Log Messages].
{stack-ov}/ml-configuring-categories.html[Categorizing Log Messages].
==== Path Parameters
[[ml-get-category-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job.
@ -29,8 +31,8 @@ For more information about categories, see
(long) Identifier for the category. If you do not specify this optional parameter,
the API returns information about all categories in the job.
==== Request Body
[[ml-get-category-request-body]]
==== {api-request-body-title}
`page`::
`from`:::
@ -38,8 +40,8 @@ For more information about categories, see
`size`:::
(integer) Specifies the maximum number of categories to obtain.
==== Results
[[ml-get-category-results]]
==== {api-response-body-title}
The API returns the following information:
@ -47,18 +49,18 @@ The API returns the following information:
(array) An array of category objects. For more information, see
<<ml-results-categories,Categories>>.
==== Authorization
[[ml-get-category-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. You also need `read` index privilege on the index
that stores the results. The `machine_learning_admin` and `machine_learning_user`
roles provide these privileges. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges] and
{xpack-ref}/built-in-roles.html[Built-in Roles].
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
==== Examples
[[ml-get-category-example]]
==== {api-examples-title}
The following example gets information about one category for the
`esxi_log` job:

27
docs/reference/ml/apis/get-datafeed-stats.asciidoc
View File

@ -10,9 +10,8 @@
Retrieves usage information for {dfeeds}.
==== Request
[[ml-get-datafeed-stats-request]]
==== {api-request-title}
`GET _ml/datafeeds/<feed_id>/_stats` +
@ -22,9 +21,8 @@ Retrieves usage information for {dfeeds}.
`GET _ml/datafeeds/_all/_stats` +
==== Description
[[ml-get-datafeed-stats-desc]]
==== {api-description-title}
You can get statistics for multiple {dfeeds} in a single API request by using a
comma-separated list of {dfeeds} or a wildcard expression. You can get
@ -36,15 +34,16 @@ If the {dfeed} is stopped, the only information you receive is the
IMPORTANT: This API returns a maximum of 10,000 {dfeeds}.
==== Path Parameters
[[ml-get-datafeed-stats-path-parms]]
==== {api-path-parms-title}
`feed_id`::
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression. If you do not specify one of these options, the API
returns statistics for all {dfeeds}.
==== Results
[[ml-get-datafeed-stats-results]]
==== {api-response-body-title}
The API returns the following information:
@ -52,15 +51,15 @@ The API returns the following information:
(array) An array of {dfeed} count objects.
For more information, see <<ml-datafeed-counts>>.
==== Authorization
[[ml-get-datafeed-stats-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-datafeed-stats-example]]
==== {api-examples-title}
The following example gets usage information for the
`datafeed-total-requests` {dfeed}:

25
docs/reference/ml/apis/get-datafeed.asciidoc
View File

@ -10,8 +10,8 @@
Retrieves configuration information for {dfeeds}.
==== Request
[[ml-get-datafeed-request]]
==== {api-request-title}
`GET _ml/datafeeds/<feed_id>` +
@ -21,8 +21,8 @@ Retrieves configuration information for {dfeeds}.
`GET _ml/datafeeds/_all` +
===== Description
[[ml-get-datafeed-desc]]
==== {api-description-title}
You can get information for multiple {dfeeds} in a single API request by using a
comma-separated list of {dfeeds} or a wildcard expression. You can get
@ -31,15 +31,16 @@ information for all {dfeeds} by using `_all`, by specifying `*` as the
IMPORTANT: This API returns a maximum of 10,000 {dfeeds}.
==== Path Parameters
[[ml-get-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id`::
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression. If you do not specify one of these options, the API
returns information about all {dfeeds}.
==== Results
[[ml-get-datafeed-results]]
==== {api-response-body-title}
The API returns the following information:
@ -47,15 +48,15 @@ The API returns the following information:
(array) An array of {dfeed} objects.
For more information, see <<ml-datafeed-resource>>.
==== Authorization
[[ml-get-datafeed-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-datafeed-example]]
==== {api-examples-title}
The following example gets configuration information for the
`datafeed-total-requests` {dfeed}:

30
docs/reference/ml/apis/get-filter.asciidoc
View File

@ -8,27 +8,27 @@
Retrieves filters.
==== Request
[[ml-get-filter-request]]
==== {api-request-title}
`GET _ml/filters/<filter_id>` +
`GET _ml/filters/`
===== Description
[[ml-get-filter-desc]]
==== {api-description-title}
You can get a single filter or all filters. For more information, see
{stack-ov}/ml-rules.html[Machine learning custom rules].
==== Path Parameters
[[ml-get-filter-path-parms]]
==== {api-path-parms-title}
`filter_id`::
(string) Identifier for the filter.
==== Request Body
[[ml-get-filter-query-parms]]
==== {api-query-parms-title}
`from`:::
(integer) Skips the specified number of filters.
@ -36,8 +36,8 @@ You can get a single filter or all filters. For more information, see
`size`:::
(integer) Specifies the maximum number of filters to obtain.
==== Results
[[ml-get-filter-results]]
==== {api-response-body-title}
The API returns the following information:
@ -45,15 +45,15 @@ The API returns the following information:
(array) An array of filter resources.
For more information, see <<ml-filter-resource>>.
==== Authorization
[[ml-get-filter-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-filter-example]]
==== {api-examples-title}
The following example gets configuration information for the `safe_domains`
filter:

29
docs/reference/ml/apis/get-influencer.asciidoc
View File

@ -8,19 +8,19 @@
Retrieves job results for one or more influencers.
==== Request
[[ml-get-influencer-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/results/influencers`
//===== Description
==== Path Parameters
[[ml-get-influencer-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job.
==== Request Body
[[ml-get-influencer-request-body]]
==== {api-request-body-title}
`desc`::
(boolean) If true, the results are sorted in descending order.
@ -48,8 +48,8 @@ Retrieves job results for one or more influencers.
`start`::
(string) Returns influencers with timestamps after this time.
==== Results
[[ml-get-influencer-results]]
==== {api-response-body-title}
The API returns the following information:
@ -57,19 +57,18 @@ The API returns the following information:
(array) An array of influencer objects.
For more information, see <<ml-results-influencers,Influencers>>.
==== Authorization
[[ml-get-influencer-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. You also need `read` index privilege on the index
that stores the results. The `machine_learning_admin` and `machine_learning_user`
roles provide these privileges. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges] and
{xpack-ref}/built-in-roles.html[Built-in Roles].
//<<security-privileges>> and <<built-in-roles>>.
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
==== Examples
[[ml-get-influencer-example]]
==== {api-examples-title}
The following example gets influencer information for the `it_ops_new_kpi` job:

28
docs/reference/ml/apis/get-job-stats.asciidoc
View File

@ -8,10 +8,8 @@
Retrieves usage information for jobs.
==== Request
[[ml-get-job-stats-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/_stats`
@ -21,8 +19,8 @@ Retrieves usage information for jobs.
`GET _ml/anomaly_detectors/_all/_stats` +
===== Description
[[ml-get-job-stats-desc]]
==== {api-description-title}
You can get statistics for multiple jobs in a single API request by using a
group name, a comma-separated list of jobs, or a wildcard expression. You can
@ -31,16 +29,16 @@ get statistics for all jobs by using `_all`, by specifying `*` as the
IMPORTANT: This API returns a maximum of 10,000 jobs.
==== Path Parameters
[[ml-get-job-stats-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) An identifier for the job. It can be a job identifier, a group name,
or a wildcard expression. If you do not specify one of these options, the API
returns statistics for all jobs.
==== Results
[[ml-get-job-stats-results]]
==== {api-response-body-title}
The API returns the following information:
@ -48,15 +46,15 @@ The API returns the following information:
(array) An array of job statistics objects.
For more information, see <<ml-jobstats,Job Statistics>>.
==== Authorization
[[ml-get-job-stats-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-job-stats-example]]
==== {api-examples-title}
The following example gets usage information for the `farequote` job:

25
docs/reference/ml/apis/get-job.asciidoc
View File

@ -8,8 +8,8 @@
Retrieves configuration information for jobs.
==== Request
[[ml-get-job-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>` +
@ -19,8 +19,8 @@ Retrieves configuration information for jobs.
`GET _ml/anomaly_detectors/_all`
===== Description
[[ml-get-job-desc]]
==== {api-description-title}
You can get information for multiple jobs in a single API request by using a
group name, a comma-separated list of jobs, or a wildcard expression. You can
@ -29,15 +29,16 @@ get information for all jobs by using `_all`, by specifying `*` as the
IMPORTANT: This API returns a maximum of 10,000 jobs.
==== Path Parameters
[[ml-get-job-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job. It can be a job identifier, a group name,
or a wildcard expression. If you do not specify one of these options, the API
returns information for all jobs.
==== Results
[[ml-get-job-results]]
==== {api-response-body-title}
The API returns the following information:
@ -45,15 +46,15 @@ The API returns the following information:
(array) An array of job resources.
For more information, see <<ml-job-resource,Job Resources>>.
==== Authorization
[[ml-get-job-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-get-job-example]]
==== {api-examples-title}
The following example gets configuration information for the `total-requests` job:

18
docs/reference/ml/apis/get-ml-info.asciidoc
View File

@ -10,28 +10,30 @@
Returns defaults and limits used by machine learning.
==== Request
[[get-ml-info-request]]
==== {api-request-title}
`GET _ml/info`
==== Description
[[get-ml-info-desc]]
==== {api-description-title}
This endpoint is designed to be used by a user interface that needs to fully
understand machine learning configurations where some options are not specified,
meaning that the defaults should be used. This endpoint may be used to find out
what those defaults are.
==== Authorization
[[get-ml-info-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. The `machine_learning_admin` and `machine_learning_user`
roles provide these privileges. For more information, see
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
{stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
==== Examples
[[get-ml-info-example]]
==== {api-examples-title}
The endpoint takes no arguments:

28
docs/reference/ml/apis/get-overall-buckets.asciidoc
View File

@ -9,7 +9,8 @@
Retrieves overall bucket results that summarize the
bucket results of multiple jobs.
==== Request
[[ml-get-overall-buckets-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/results/overall_buckets` +
@ -17,7 +18,8 @@ bucket results of multiple jobs.
`GET _ml/anomaly_detectors/_all/results/overall_buckets`
==== Description
[[ml-get-overall-buckets-desc]]
==== {api-description-title}
You can summarize the bucket results for all jobs by using `_all` or by
specifying `*` as the `<job_id>`.
@ -41,13 +43,15 @@ to request overall buckets that span longer than the largest job's `bucket_span`
When set, the `overall_score` will be the max `overall_score` of the corresponding
overall buckets with a span equal to the largest job's `bucket_span`.
==== Path Parameters
[[ml-get-overall-buckets-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job. It can be a job identifier, a group name, a
comma-separated list of jobs or groups, or a wildcard expression.
==== Request Body
[[ml-get-overall-buckets-request-body]]
==== {api-request-body-title}
`allow_no_jobs`::
(boolean) If `false` and the `job_id` does not match any job an error will
@ -76,8 +80,8 @@ overall buckets with a span equal to the largest job's `bucket_span`.
(integer) The number of top job bucket scores to be used in the
`overall_score` calculation. The default value is `1`.
===== Results
[[ml-get-overall-buckets-results]]
==== {api-response-body-title}
The API returns the following information:
@ -85,18 +89,18 @@ The API returns the following information:
(array) An array of overall bucket objects. For more information, see
<<ml-results-overall-buckets,Overall Buckets>>.
==== Authorization
[[ml-get-overall-buckets-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. You also need `read` index privilege on the index
that stores the results. The `machine_learning_admin` and `machine_learning_user`
roles provide these privileges. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges] and
{xpack-ref}/built-in-roles.html[Built-in Roles].
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
==== Examples
[[ml-get-overall-buckets-example]]
==== {api-examples-title}
The following example gets overall buckets for jobs with IDs matching `job-*`:

30
docs/reference/ml/apis/get-record.asciidoc
View File

@ -8,20 +8,19 @@
Retrieves anomaly records for a job.
==== Request
[[ml-get-record-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/results/records`
//===== Description
==== Path Parameters
[[ml-get-record-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job.
==== Request Body
[[ml-get-record-request-body]]
==== {api-request-body-title}
`desc`::
(boolean) If true, the results are sorted in descending order.
@ -49,8 +48,8 @@ Retrieves anomaly records for a job.
`start`::
(string) Returns records with timestamps after this time.
==== Results
[[ml-get-record-results]]
==== {api-response-body-title}
The API returns the following information:
@ -58,19 +57,18 @@ The API returns the following information:
(array) An array of record objects. For more information, see
<<ml-results-records,Records>>.
==== Authorization
[[ml-get-record-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. You also need `read` index privilege on the index
that stores the results. The `machine_learning_admin` and `machine_learning_user`
roles provide these privileges. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges] and
{xpack-ref}/built-in-roles.html[Built-in Roles].
//<<security-privileges>> and <<built-in-roles>>.
{stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
==== Examples
[[ml-get-record-example]]
==== {api-examples-title}
The following example gets record information for the `it-ops-kpi` job:

27
docs/reference/ml/apis/get-snapshot.asciidoc
View File

@ -8,16 +8,15 @@
Retrieves information about model snapshots.
==== Request
[[ml-get-snapshot-request]]
==== {api-request-title}
`GET _ml/anomaly_detectors/<job_id>/model_snapshots` +
`GET _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
//===== Description
==== Path Parameters
[[ml-get-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id`::
(string) Identifier for the job.
@ -26,7 +25,8 @@ Retrieves information about model snapshots.
(string) Identifier for the model snapshot. If you do not specify this
optional parameter, the API returns information about all model snapshots.
==== Request Body
[[ml-get-snapshot-request-body]]
==== {api-request-body-title}
`desc`::
(boolean) If true, the results are sorted in descending order.
@ -47,8 +47,8 @@ Retrieves information about model snapshots.
`start`::
(string) Returns snapshots with timestamps after this time.
==== Results
[[ml-get-snapshot-results]]
==== {api-response-body-title}
The API returns the following information:
@ -56,16 +56,15 @@ The API returns the following information:
(array) An array of model snapshot objects. For more information, see
<<ml-snapshot-resource,Model Snapshots>>.
==== Authorization
[[ml-get-snapshot-prereqs]]
==== {api-prereq-title}
You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
privileges to use this API. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-get-snapshot-example]]
==== {api-examples-title}
The following example gets model snapshot information for the
`it_ops_new_logs` job:

26
docs/reference/ml/apis/open-job.asciidoc
View File

@ -10,41 +10,41 @@ Opens one or more jobs.
A job must be opened in order for it to be ready to receive and analyze data.
A job can be opened and closed multiple times throughout its lifecycle.
==== Request
[[ml-open-job-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/{job_id}/_open`
==== Description
[[ml-open-job-desc]]
==== {api-description-title}
When you open a new job, it starts with an empty model.
When you open an existing job, the most recent model state is automatically loaded.
The job is ready to resume its analysis from where it left off, once new data is received.
==== Path Parameters
[[ml-open-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
==== Request Body
[[ml-open-job-request-body]]
==== {api-request-body-title}
`timeout`::
(time) Controls the time to wait until a job has opened.
The default value is 30 minutes.
==== Authorization
[[ml-open-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-open-job-example]]
==== {api-examples-title}
The following example opens the `total-requests` job and sets an optional
property:

26
docs/reference/ml/apis/post-calendar-event.asciidoc
View File

@ -8,38 +8,40 @@
Posts scheduled events in a calendar.
==== Request
[[ml-post-calendar-event-request]]
==== {api-request-title}
`POST _ml/calendars/<calendar_id>/events`
[[ml-post-calendar-event-desc]]
==== {api-description-title}
==== Description
This API accepts a list of {xpack-ref}/ml-calendars.html[scheduled events], each
This API accepts a list of {stack-ov}/ml-calendars.html[scheduled events], each
of which must have a start time, end time, and description.
==== Path Parameters
[[ml-post-calendar-event-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
(string) Identifier for the calendar.
==== Request Body
[[ml-post-calendar-event-request-body]]
==== {api-request-body-title}
`events`::
(array) A list of one of more scheduled events. The event's start and end times
may be specified as integer milliseconds since the epoch or as a string in ISO 8601
format. See <<ml-event-resource>>.
==== Authorization
[[ml-post-calendar-event-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-post-calendar-event-example]]
==== {api-examples-title}
You can add scheduled events to the `planned-outages` calendar as follows:

31
docs/reference/ml/apis/post-data.asciidoc
View File

@ -8,13 +8,13 @@
Sends data to an anomaly detection job for analysis.
==== Request
[[ml-post-data-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/_data`
==== Description
[[ml-post-data-desc]]
==== {api-description-title}
The job must have a state of `open` to receive and process the data.
@ -42,14 +42,14 @@ IMPORTANT: For each job, data can only be accepted from a single connection at
a time. It is not currently possible to post data to multiple jobs using wildcards
or a comma-separated list.
==== Path Parameters
[[ml-post-data-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
==== Query Parameters
[[ml-post-data-query-parms]]
==== {api-query-parms-title}
`reset_start`::
(string) Specifies the start of the bucket resetting range
@ -57,22 +57,21 @@ or a comma-separated list.
`reset_end`::
(string) Specifies the end of the bucket resetting range
==== Request Body
[[ml-post-data-request-body]]
==== {api-request-body-title}
A sequence of one or more JSON documents containing the data to be analyzed.
Only whitespace characters are permitted in between the documents.
==== Authorization
[[ml-post-data-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-post-data-example]]
==== {api-examples-title}
The following example posts data from the it_ops_new_kpi.json file to the `it_ops_new_kpi` job:

24
docs/reference/ml/apis/preview-datafeed.asciidoc
View File

@ -10,33 +10,33 @@
Previews a {dfeed}.
==== Request
[[ml-preview-datafeed-request]]
==== {api-request-title}
`GET _ml/datafeeds/<datafeed_id>/_preview`
==== Description
[[ml-preview-datafeed-desc]]
==== {api-description-title}
The preview {dfeeds} API returns the first "page" of results from the `search`
that is created by using the current {dfeed} settings. This preview shows the
structure of the data that will be passed to the anomaly detection engine.
==== Path Parameters
[[ml-preview-datafeed-path-parms]]
==== {api-path-parms-title}
`datafeed_id` (required)::
(string) Identifier for the {dfeed}
==== Authorization
[[ml-preview-datafeed-prereqs]]
==== {api-prereq-title}
If {es} {security-features} are enabled, you must have `monitor_ml`, `monitor`,
`manage_ml`, or `manage` cluster privileges to use this API. For more
information, see
{stack-ov}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
[[ml-preview-datafeed-security]]
==== Security Integration
When {es} {security-features} are enabled, the {dfeed} query is previewed using
@ -47,8 +47,8 @@ not accurately reflect what the {dfeed} will return when started. To avoid
such problems, the same user that creates/updates the {dfeed} should preview
it to ensure it is returning the expected data.
==== Examples
[[ml-preview-datafeed-example]]
==== {api-examples-title}
The following example obtains a preview of the `datafeed-farequote` {dfeed}:

16
docs/reference/ml/apis/put-calendar-job.asciidoc
View File

@ -8,12 +8,13 @@
Adds a job to a calendar.
==== Request
[[ml-put-calendar-job-request]]
==== {api-request-title}
`PUT _ml/calendars/<calendar_id>/jobs/<job_id>`
==== Path Parameters
[[ml-put-calendar-job-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
(string) Identifier for the calendar.
@ -22,14 +23,15 @@ Adds a job to a calendar.
(string) An identifier for the job. It can be a job identifier, a group name, or a
comma-separated list of jobs or groups.
==== Authorization
[[ml-put-calendar-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security Privileges].
==== Examples
[[ml-put-calendar-job-example]]
==== {api-examples-title}
The following example associates the `planned-outages` calendar with the
`total-requests` job:

25
docs/reference/ml/apis/put-calendar.asciidoc
View File

@ -8,35 +8,38 @@
Instantiates a calendar.
==== Request
[[ml-put-calendar-request]]
==== {api-request-title}
`PUT _ml/calendars/<calendar_id>`
===== Description
[[ml-put-calendar-desc]]
==== {api-description-title}
For more information, see
{xpack-ref}/ml-calendars.html[Calendars and Scheduled Events].
{stack-ov}/ml-calendars.html[Calendars and Scheduled Events].
==== Path Parameters
[[ml-put-calendar-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
(string) Identifier for the calendar.
==== Request Body
[[ml-put-calendar-request-body]]
==== {api-request-body-title}
`description`::
(string) A description of the calendar.
==== Authorization
[[ml-put-calendar-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-put-calendar-example]]
==== {api-examples-title}
The following example creates the `planned-outages` calendar:

28
docs/reference/ml/apis/put-datafeed.asciidoc
View File

@ -10,13 +10,13 @@
Instantiates a {dfeed}.
==== Request
[[ml-put-datafeed-request]]
==== {api-request-title}
`PUT _ml/datafeeds/<feed_id>`
==== Description
[[ml-put-datafeed-desc]]
==== {api-description-title}
You must create a job before you create a {dfeed}. You can associate only one
{dfeed} to each job.
@ -26,16 +26,16 @@ IMPORTANT: You must use {kib} or this API to create a {dfeed}. Do not put a {df
If {es} {security-features} are enabled, do not give users `write`
privileges on the `.ml-config` index.
==== Path Parameters
[[ml-put-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) A numerical character string that uniquely identifies the {dfeed}.
This identifier can contain lowercase alphanumeric characters (a-z and 0-9),
hyphens, and underscores. It must start and end with alphanumeric characters.
==== Request Body
[[ml-put-datafeed-request-body]]
==== {api-request-body-title}
`aggregations`::
(object) If set, the {dfeed} performs aggregation searches.
@ -90,22 +90,22 @@ IMPORTANT: You must use {kib} or this API to create a {dfeed}. Do not put a {df
For more information about these properties,
see <<ml-datafeed-resource>>.
==== Authorization
[[ml-put-datafeed-prereqs]]
==== {api-prereq-title}
If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
cluster privileges to use this API. For more information, see
{stack-ov}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
[[ml-put-datafeed-security]]
==== Security integration
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.
==== Examples
[[ml-put-datafeed-example]]
==== {api-examples-title}
The following example creates the `datafeed-total-requests` {dfeed}:

23
docs/reference/ml/apis/put-filter.asciidoc
View File

@ -8,23 +8,26 @@
Instantiates a filter.
==== Request
[[ml-put-filter-request]]
==== {api-request-title}
`PUT _ml/filters/<filter_id>`
===== Description
[[ml-put-filter-desc]]
==== {api-description-title}
A {stack-ov}/ml-rules.html[filter] contains a list of strings.
It can be used by one or more jobs. Specifically, filters are referenced in
the `custom_rules` property of <<ml-detectorconfig,detector configuration objects>>.
==== Path Parameters
[[ml-put-filter-path-parms]]
==== {api-path-parms-title}
`filter_id` (required)::
(string) Identifier for the filter.
==== Request Body
[[ml-put-filter-request-body]]
==== {api-request-body-title}
`description`::
(string) A description of the filter.
@ -35,15 +38,15 @@ the `custom_rules` property of <<ml-detectorconfig,detector configuration object
or the end of an item. Up to 10000 items
are allowed in each filter.
==== Authorization
[[ml-put-filter-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-put-filter-example]]
==== {api-examples-title}
The following example creates the `safe_domains` filter:

23
docs/reference/ml/apis/put-job.asciidoc
View File

@ -8,27 +8,29 @@
Instantiates a job.
==== Request
[[ml-put-job-request]]
==== {api-request-title}
`PUT _ml/anomaly_detectors/<job_id>`
===== Description
[[ml-put-job-desc]]
==== {api-description-title}
IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
directly to the `.ml-config` index using the Elasticsearch index API.
If {es} {security-features} are enabled, do not give users `write`
privileges on the `.ml-config` index.
==== Path Parameters
[[ml-put-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job. This identifier can contain lowercase
alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must
start and end with alphanumeric characters.
==== Request Body
[[ml-put-job-request-body]]
==== {api-request-body-title}
`analysis_config`::
(object) The analysis configuration, which specifies how to analyze the data.
@ -78,14 +80,15 @@ IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
(long) Advanced configuration option. The number of days for which job results
are retained. See <<ml-job-resource>>.
==== Authorization
[[ml-put-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-put-job-example]]
==== {api-examples-title}
The following example creates the `total-requests` job:

24
docs/reference/ml/apis/revert-snapshot.asciidoc
View File

@ -8,12 +8,13 @@
Reverts to a specific snapshot.
==== Request
[[ml-revert-snapshot-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_revert`
==== Description
[[ml-revert-snapshot-desc]]
==== {api-description-title}
The {ml} feature in {xpack} reacts quickly to anomalous input, learning new
behaviors in data. Highly anomalous input increases the variance in the models
@ -25,8 +26,8 @@ Friday or a critical system failure.
IMPORTANT: Before you revert to a saved snapshot, you must close the job.
==== Path Parameters
[[ml-revert-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
@ -34,7 +35,8 @@ IMPORTANT: Before you revert to a saved snapshot, you must close the job.
`snapshot_id` (required)::
(string) Identifier for the model snapshot
==== Request Body
[[ml-revert-snapshot-request-body]]
==== {api-request-body-title}
`delete_intervening_results`::
(boolean) If true, deletes the results in the time period between the
@ -45,15 +47,15 @@ NOTE: If you choose not to delete intervening results when reverting a snapshot,
the job will not accept input data that is older than the current time.
If you want to resend data, then delete the intervening results.
==== Authorization
[[ml-revert-snapshot-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-revert-snapshot-example]]
==== {api-examples-title}
The following example reverts to the `1491856080` snapshot for the
`it_ops_new_kpi` job:

17
docs/reference/ml/apis/set-upgrade-mode.asciidoc
View File

@ -9,7 +9,8 @@
Sets a cluster wide upgrade_mode setting that prepares {ml} indices for an
upgrade.
==== Request
[[ml-set-upgrade-mode-request]]
==== {api-request-title}
//////////////////////////
[source,js]
@ -25,7 +26,8 @@ POST /_ml/set_upgrade_mode?enabled=false&timeout=10m
`POST _ml/set_upgrade_mode`
==== Description
[[ml-set-upgrade-mode-desc]]
==== {api-description-title}
When upgrading your cluster, in some circumstances you must restart your nodes and
reindex your {ml} indices. In those circumstances, there must be no {ml} jobs running.
@ -37,7 +39,6 @@ though stopping jobs is not a requirement in that case.
For more information, see {stack-ref}/upgrading-elastic-stack.html[Upgrading the {stack}].
When `enabled=true` this API temporarily halts all job and {dfeed} tasks and
prohibits new job and {dfeed} tasks from starting.
@ -50,7 +51,8 @@ You can see the current value for the `upgrade_mode` setting by using the
IMPORTANT: No new {ml} jobs can be opened while the `upgrade_mode` setting is
`true`.
==== Query Parameters
[[ml-set-upgrade-mode-query-parms]]
==== {api-query-parms-title}
`enabled`::
(boolean) When `true`, this enables `upgrade_mode`. Defaults to `false`
@ -59,14 +61,15 @@ IMPORTANT: No new {ml} jobs can be opened while the `upgrade_mode` setting is
(time) The time to wait for the request to be completed.
The default value is 30 seconds.
==== Authorization
[[ml-set-upgrade-mode-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-set-upgrade-mode-example]]
==== {api-examples-title}
The following example enables `upgrade_mode` for the cluster:

25
docs/reference/ml/apis/start-datafeed.asciidoc
View File

@ -12,11 +12,13 @@ Starts one or more {dfeeds}.
A {dfeed} must be started in order to retrieve data from {es}.
A {dfeed} can be started and stopped multiple times throughout its lifecycle.
==== Request
[[ml-start-datafeed-request]]
==== {api-request-title}
`POST _ml/datafeeds/<feed_id>/_start`
==== Description
[[ml-start-datafeed-desc]]
==== {api-description-title}
NOTE: Before you can start a {dfeed}, the job must be open. Otherwise, an error
occurs.
@ -56,13 +58,14 @@ If you specify a `start` value that is earlier than the timestamp of the latest
processed record, the {dfeed} continues from 1 millisecond after the timestamp
of the latest processed record.
==== Path Parameters
[[ml-start-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) Identifier for the {dfeed}
==== Request Body
[[ml-start-datafeed-request-body]]
==== {api-request-body-title}
`end`::
(string) The time that the {dfeed} should end. This value is exclusive.
@ -76,22 +79,22 @@ of the latest processed record.
(time) Controls the amount of time to wait until a {dfeed} starts.
The default value is 20 seconds.
==== Authorization
[[ml-start-datafeed-prereqs]]
==== {api-prereq-title}
If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
cluster privileges to use this API. For more information, see
{stack-ov}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
[[ml-start-datafeed-security]]
==== Security integration
When {es} {security-features} are enabled, your {dfeed} remembers which roles the
last user to create or update it had at the time of creation/update and runs the
query using those same roles.
==== Examples
[[ml-start-datafeed-example]]
==== {api-examples-title}
The following example starts the `datafeed-it-ops-kpi` {dfeed}:

25
docs/reference/ml/apis/stop-datafeed.asciidoc
View File

@ -13,7 +13,8 @@ Stops one or more {dfeeds}.
A {dfeed} that is stopped ceases to retrieve data from {es}.
A {dfeed} can be started and stopped multiple times throughout its lifecycle.
==== Request
[[ml-stop-datafeed-request]]
==== {api-request-title}
`POST _ml/datafeeds/<feed_id>/_stop` +
@ -21,22 +22,22 @@ A {dfeed} can be started and stopped multiple times throughout its lifecycle.
`POST _ml/datafeeds/_all/_stop`
===== Description
[[ml-stop-datafeed-desc]]
==== {api-description-title}
You can stop multiple {dfeeds} in a single API request by using a
comma-separated list of {dfeeds} or a wildcard expression. You can close all
{dfeeds} by using `_all` or by specifying `*` as the `<feed_id>`.
==== Path Parameters
[[ml-stop-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id`::
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression.
==== Request Body
[[ml-stop-datafeed-request-body]]
==== {api-request-body-title}
`force`::
(boolean) If true, the {dfeed} is stopped forcefully.
@ -45,15 +46,15 @@ comma-separated list of {dfeeds} or a wildcard expression. You can close all
(time) Controls the amount of time to wait until a {dfeed} stops.
The default value is 20 seconds.
==== Authorization
[[ml-stop-datafeed-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-stop-datafeed-example]]
==== {api-examples-title}
The following example stops the `datafeed-total-requests` {dfeed}:

24
docs/reference/ml/apis/update-datafeed.asciidoc
View File

@ -10,21 +10,25 @@
Updates certain properties of a {dfeed}.
==== Request
[[ml-update-datafeed-request]]
==== {api-request-title}
`POST _ml/datafeeds/<feed_id>/_update`
===== Description
[[ml-update-datafeed-desc]]
==== {api-description-title}
NOTE: If you update the `delayed_data_check_config` property, you must stop and
start the {dfeed} for the change to be applied.
==== Path Parameters
[[ml-update-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) Identifier for the {dfeed}
==== Request Body
[[ml-update-datafeed-request-body]]
==== {api-request-body-title}
The following properties can be updated after the {dfeed} is created:
@ -80,22 +84,22 @@ The following properties can be updated after the {dfeed} is created:
For more information about these properties,
see <<ml-datafeed-resource>>.
==== Authorization
[[ml-update-datafeed-prereqs]]
==== {api-prereq-title}
If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
cluster privileges to use this API. For more information, see
{stack-ov}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
[[ml-update-datafeed-security]]
==== Security Integration
When {es} {security-features} are enabled, your {dfeed} remembers which roles the
user who updated it had at the time of update and runs the query using those
same roles.
==== Examples
[[ml-update-datafeed-example]]
==== {api-examples-title}
The following example updates the query for the `datafeed-total-requests`
{dfeed} so that only log entries of error level are analyzed:

20
docs/reference/ml/apis/update-filter.asciidoc
View File

@ -8,18 +8,18 @@
Updates the description of a filter, adds items, or removes items.
==== Request
[[ml-update-filter-request]]
==== {api-request-title}
`POST _ml/filters/<filter_id>/_update`
//==== Description
==== Path Parameters
[[ml-update-filter-path-parms]]
==== {api-path-parms-title}
`filter_id` (required)::
(string) Identifier for the filter.
[[ml-update-filter-request-body]]
==== Request Body
`description`::
@ -31,15 +31,15 @@ Updates the description of a filter, adds items, or removes items.
`remove_items`::
(array of strings) The items to remove from the filter.
==== Authorization
[[ml-update-filter-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-update-filter-example]]
==== {api-examples-title}
You can change the description, add and remove items to the `safe_domains` filter as follows:

19
docs/reference/ml/apis/update-job.asciidoc
View File

@ -8,17 +8,19 @@
Updates certain properties of a job.
==== Request
[[ml-update-job-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/_update`
==== Path Parameters
[[ml-update-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
==== Request Body
[[ml-update-job-request-body]]
==== {api-request-body-title}
The following properties can be updated after the job is created:
@ -86,14 +88,15 @@ A detector update object has the following properties:
No other detector property can be updated.
==== Authorization
[[ml-update-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-update-job-example]]
==== {api-examples-title}
The following example updates the `total-requests` job:

23
docs/reference/ml/apis/update-snapshot.asciidoc
View File

@ -8,14 +8,13 @@
Updates certain properties of a snapshot.
==== Request
[[ml-update-snapshot-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_update`
//==== Description
==== Path Parameters
[[ml-update-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
@ -23,7 +22,8 @@ Updates certain properties of a snapshot.
`snapshot_id` (required)::
(string) Identifier for the model snapshot
==== Request Body
[[ml-update-snapshot-request-body]]
==== {api-request-body-title}
The following properties can be updated after the model snapshot is created:
@ -37,16 +37,15 @@ The following properties can be updated after the model snapshot is created:
Note that this snapshot will still be deleted when the job is deleted.
The default value is false.
==== Authorization
[[ml-update-snapshot-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
//<<privileges-list-cluster>>.
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-update-snapshot-example]]
==== {api-examples-title}
The following example updates the snapshot identified as `1491852978`:

20
docs/reference/ml/apis/validate-detector.asciidoc
View File

@ -8,30 +8,32 @@
Validates detector configuration information.
==== Request
[[ml-valid-detector-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/_validate/detector`
==== Description
[[ml-valid-detector-desc]]
==== {api-description-title}
The validate detectors API enables you validate the detector configuration
before you create a job.
==== Request Body
[[ml-valid-detector-request-body]]
==== {api-request-body-title}
For a list of the properties that you can specify in the body of this API,
see <<ml-detectorconfig,detector configuration objects>>.
==== Authorization
[[ml-valid-detector-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-valid-detector-example]]
==== {api-examples-title}
The following example validates detector configuration information:

20
docs/reference/ml/apis/validate-job.asciidoc
View File

@ -8,30 +8,32 @@
Validates job configuration information.
==== Request
[[ml-valid-job-request]]
==== {api-request-title}
`POST _ml/anomaly_detectors/_validate`
==== Description
[[ml-valid-job-desc]]
==== {api-description-title}
The validate jobs API enables you validate the job configuration before you
create the job.
==== Request Body
[[ml-valid-job-request-body]]
==== {api-request-body-title}
For a list of the properties that you can specify in the body of this API,
see <<ml-job-resource,Job Resources>>.
==== Authorization
[[ml-valid-job-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
{stack-ov}/security-privileges.html[Security privileges].
==== Examples
[[ml-valid-job-example]]
==== {api-examples-title}
The following example validates job configuration information: