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

[DOCS] Updates ML APIs to use new API template (#43711)

This commit is contained in:
Lisa Cawley 2019-06-27 13:58:42 -07:00 committed by lcawl
parent 68dbbd8793
commit 42cb59f7b4
46 changed files with 615 additions and 607 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -22,6 +22,13 @@ operations, but you can still explore and navigate results.
`POST _ml/anomaly_detectors/_all/_close` +
[[ml-close-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-close-job-desc]]
==== {api-description-title}
@ -52,27 +59,21 @@ results the job might have recently produced or might produce in the future.
[[ml-close-job-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(string) Identifier for the job. It can be a job identifier, a group name, or
a wildcard expression.
[[ml-close-job-query-parms]]
==== {api-query-parms-title}
`force`::
`force` (Optional)::
(boolean) Use to close a failed job, or to forcefully close a job which has not
responded to its initial close request.
`timeout`::
`timeout` (Optional)::
(time units) Controls the time to wait until a job has closed.
The default value is 30 minutes.
[[ml-close-job-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].
[[ml-close-job-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Deletes scheduled events from a calendar.
`DELETE _ml/calendars/<calendar_id>/events/<event_id>`
[[ml-delete-calendar-event-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-calendar-event-desc]]
==== {api-description-title}
@ -23,19 +30,13 @@ events and delete the calendar, see the
[[ml-delete-calendar-event-path-parms]]
==== {api-path-parms-title}
`calendar_id`(required)::
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
`event_id` (required)::
`<event_id>` (Required)::
(string) Identifier for the scheduled event. You can obtain this identifier
by using the <<ml-get-calendar-event,get calendar events API>>.
[[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 {stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-calendar-event-example]]
==== {api-examples-title}

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

@ -13,21 +13,22 @@ Deletes jobs from a calendar.
`DELETE _ml/calendars/<calendar_id>/jobs/<job_id>`
[[ml-delete-calendar-job-path-parms]]
==== {api-path-parms-title}
`calendar_id`(required)::
(string) Identifier for the calendar.
`job_id` (required)::
(string) An identifier for the job. It can be a job identifier, a group name, or a
comma-separated list of jobs or groups.
[[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 {stack-ov}/security-privileges.html[Security privileges].
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-calendar-job-path-parms]]
==== {api-path-parms-title}
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
`<job_id>` (Required)::
(string) An identifier for the job. It can be a job identifier, a group name,
or a comma-separated list of jobs or groups.
[[ml-delete-calendar-job-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Deletes a calendar.
`DELETE _ml/calendars/<calendar_id>`
[[ml-delete-calendar-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-calendar-desc]]
==== {api-description-title}
@ -22,15 +29,9 @@ calendar.
[[ml-delete-calendar-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
[[ml-delete-calendar-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].
[[ml-delete-calendar-example]]
==== {api-examples-title}

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

@ -15,29 +15,31 @@ Deletes an existing {dfeed}.
`DELETE _ml/datafeeds/<feed_id>`
[[ml-delete-datafeed-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-datafeed-desc]]
==== {api-description-title}
NOTE: Unless the `force` parameter is used, the {dfeed} must be stopped before it can be deleted.
NOTE: Unless you use the `force` parameter, you must stop the {dfeed} before you
can delete it.
[[ml-delete-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) Identifier for the {dfeed}
`<feed_id>` (Required)::
(string) Identifier for the {dfeed}.
[[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}.
[[ml-delete-datafeed-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].
`force` (Optional)::
(boolean) Use to forcefully delete a started {dfeed}; this method is quicker
than stopping and deleting the {dfeed}.
[[ml-delete-datafeed-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Deletes expired and unused machine learning data.
`DELETE _ml/_delete_expired_data`
[[ml-delete-expired-data-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-expired-data-desc]]
==== {api-description-title}
@ -20,14 +27,6 @@ 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.
[[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].
[[ml-delete-expired-data-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Deletes a filter.
`DELETE _ml/filters/<filter_id>`
[[ml-delete-filter-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-filter-desc]]
==== {api-description-title}
@ -23,15 +30,9 @@ update or delete the job before you can delete the filter.
[[ml-delete-filter-path-parms]]
==== {api-path-parms-title}
`filter_id` (required)::
`<filter_id>` (Required)::
(string) Identifier for the filter.
[[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].
[[ml-delete-filter-example]]
==== {api-examples-title}

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

@ -17,47 +17,51 @@ Deletes forecasts from a {ml} job.
`DELETE _ml/anomaly_detectors/<job_id>/_forecast/_all`
[[ml-delete-forecast-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[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.
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.
NOTE: When you delete a job its associated forecasts are deleted.
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].
For more information, see
{stack-ov}/ml-overview.html#ml-forecasting[Forecasting the future].
[[ml-delete-forecast-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
`<job_id>` (Required)::
(string) Identifier for the job.
`forecast_id`::
`forecast_id` (Optional)::
(string) A comma-separated list of forecast identifiers.
If you do not specify this optional parameter or if you specify `_all`, the
API deletes all forecasts from the job.
[[ml-delete-forecast-request-body]]
==== {api-request-body-title}
[[ml-delete-forecast-query-parms]]
==== {api-query-parms-title}
`allow_no_forecasts`::
`allow_no_forecasts` (Optional)::
(boolean) Specifies whether an error occurs when there are no forecasts. In
particular, if this parameter is set to `false` and there are no forecasts
associated with the job, attempts to delete all forecasts return an error.
The default value is `true`.
`timeout`::
`timeout` (Optional)::
(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 <<time-units>>.
[[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].
[[ml-delete-forecast-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Deletes an existing anomaly detection job.
`DELETE _ml/anomaly_detectors/<job_id>`
[[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. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-job-desc]]
==== {api-description-title}
@ -33,27 +40,20 @@ separated list.
[[ml-delete-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
[[ml-delete-job-query-parms]]
==== {api-query-parms-title}
`force`::
`force` (Optional)::
(boolean) Use to forcefully delete an opened job; this method is quicker than
closing and deleting the job.
`wait_for_completion`::
`wait_for_completion` (Optional)::
(boolean) Specifies whether the request should return immediately or wait
until the job deletion completes. Defaults to `true`.
[[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].
[[ml-delete-job-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Deletes an existing model snapshot.
`DELETE _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
[[ml-delete-snapshot-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-delete-snapshot-desc]]
==== {api-description-title}
@ -23,17 +30,11 @@ the `model_snapshot_id` in the results from the get jobs API.
[[ml-delete-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
`snapshot_id` (required)::
(string) Identifier for the model snapshot
[[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].
`<snapshot_id>` (Required)::
(string) Identifier for the model snapshot.
[[ml-delete-snapshot-example]]
==== {api-examples-title}

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

@ -16,6 +16,13 @@ suitable to be ingested into {es}.
`POST _ml/find_file_structure`
[[ml-find-file-structure-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml` or
`monitor` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-find-file-structure-desc]]
==== {api-description-title}
@ -51,36 +58,36 @@ chosen.
[[ml-find-file-structure-query-parms]]
==== {api-query-parms-title}
`charset`::
`charset` (Optional)::
(string) The file's character set. It must be a character set that is supported
by the JVM that {es} uses. For example, `UTF-8`, `UTF-16LE`, `windows-1252`, or
`EUC-JP`. If this parameter is not specified, the structure finder chooses an
appropriate character set.
`column_names`::
`column_names` (Optional)::
(string) If you have set `format` to `delimited`, you can specify the column names
in a comma-separated list. If this parameter is not specified, the structure
finder uses the column names from the header row of the file. If the file does
not have a header role, columns are named "column1", "column2", "column3", etc.
`delimiter`::
`delimiter` (Optional)::
(string) If you have set `format` to `delimited`, you can specify the character used
to delimit the values in each row. Only a single character is supported; the
delimiter cannot have multiple characters. If this parameter is not specified,
the structure finder considers the following possibilities: comma, tab,
semi-colon, and pipe (`|`).
`explain`::
`explain` (Optional)::
(boolean) If this parameter is set to `true`, the response includes a field
named `explanation`, which is an array of strings that indicate how the
structure finder produced its result. The default value is `false`.
`format`::
`format` (Optional)::
(string) The high level structure of the file. Valid values are `ndjson`, `xml`,
`delimited`, and `semi_structured_text`. If this parameter is not specified,
the structure finder chooses one.
`grok_pattern`::
`grok_pattern` (Optional)::
(string) If you have set `format` to `semi_structured_text`, you can specify a Grok
pattern that is used to extract fields from every message in the file. The
name of the timestamp field in the Grok pattern must match what is specified
@ -88,20 +95,20 @@ chosen.
name of the timestamp field in the Grok pattern must match "timestamp". If
`grok_pattern` is not specified, the structure finder creates a Grok pattern.
`has_header_row`::
`has_header_row` (Optional)::
(boolean) If you have set `format` to `delimited`, you can use this parameter to
indicate whether the column names are in the first row of the file. If this
parameter is not specified, the structure finder guesses based on the similarity of
the first row of the file to other rows.
`line_merge_size_limit`::
`line_merge_size_limit` (Optional)::
(unsigned integer) The maximum number of characters in a message when lines are
merged to form messages while analyzing semi-structured files. The default
is 10000. If you have extremely long messages you may need to increase this, but
be aware that this may lead to very long processing times if the way to group
lines into messages is misdetected.
`lines_to_sample`::
`lines_to_sample` (Optional)::
(unsigned integer) The number of lines to include in the structural analysis,
starting from the beginning of the file. The minimum is 2; the default
is 1000. If the value of this parameter is greater than the number of lines in
@ -117,7 +124,7 @@ efficient to upload a sample file with more variety in the first 1000 lines than
to request analysis of 100000 lines to achieve some variety.
--
`quote`::
`quote` (Optional)::
(string) If you have set `format` to `delimited`, you can specify the character used
to quote the values in each row if they contain newlines or the delimiter
character. Only a single character is supported. If this parameter is not
@ -125,18 +132,18 @@ to request analysis of 100000 lines to achieve some variety.
format does not use quoting, a workaround is to set this argument to a
character that does not appear anywhere in the sample.
`should_trim_fields`::
`should_trim_fields` (Optional)::
(boolean) If you have set `format` to `delimited`, you can specify whether values
between delimiters should have whitespace trimmed from them. If this parameter
is not specified and the delimiter is pipe (`|`), the default value is `true`.
Otherwise, the default value is `false`.
`timeout`::
`timeout` (Optional)::
(time) Sets the maximum amount of time that the structure analysis make take.
If the analysis is still running when the timeout expires then it will be
aborted. The default value is 25 seconds.
`timestamp_field`::
`timestamp_field` (Optional)::
(string) The name of the field that contains the primary timestamp of each
record in the file. In particular, if the file were ingested into an index,
this is the field that would be used to populate the `@timestamp` field. +
@ -155,7 +162,7 @@ field (if any) is the primary timestamp field. For structured file formats, it
is not compulsory to have a timestamp in the file.
--
`timestamp_format`::
`timestamp_format` (Optional)::
(string) The Java time format of the timestamp field in the file. +
+
--
@ -207,13 +214,6 @@ 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.
[[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]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Forces any buffered data to be processed by the job.
`POST _ml/anomaly_detectors/<job_id>/_flush`
[[ml-flush-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-flush-job-desc]]
==== {api-description-title}
@ -29,39 +36,33 @@ opened again before analyzing further data.
[[ml-flush-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
[[ml-flush-job-query-parms]]
==== {api-query-parms-title}
`advance_time`::
`advance_time` (Optional)::
(string) Specifies to advance to a particular time value. Results are
generated and the model is updated for data from the specified time interval.
`calc_interim`::
`calc_interim` (Optional)::
(boolean) If true, calculates the interim results for the most recent bucket
or all buckets within the latency period.
`end`::
`end` (Optional)::
(string) When used in conjunction with `calc_interim`, specifies the range
of buckets on which to calculate interim results.
`skip_time`::
`skip_time` (Optional)::
(string) Specifies to skip to a particular time value. Results are not
generated and the model is not updated for data from the specified time
interval.
`start`::
`start` (Optional)::
(string) When used in conjunction with `calc_interim`, specifies the range of
buckets on which to calculate interim results.
[[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].
[[ml-flush-job-example]]
==== {api-examples-title}

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

@ -13,10 +13,17 @@ Predicts the future behavior of a time series by using its historical behavior.
`POST _ml/anomaly_detectors/<job_id>/_forecast`
[[ml-forecast-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-forecast-desc]]
==== {api-description-title}
See {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the Future].
See {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the future].
[NOTE]
===============================
@ -29,30 +36,24 @@ forecast. For more information about this property, see <<ml-job-resource>>.
[[ml-forecast-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(string) Identifier for the job.
[[ml-forecast-request-body]]
==== {api-request-body-title}
`duration`::
`duration` (Optional)::
(time units) A period of time that indicates how far into the future to
forecast. For example, `30d` corresponds to 30 days. The default value is 1
day. The forecast starts at the last record that was processed. For more
information about time units, see <<time-units>>.
`expires_in`::
`expires_in` (Optional)::
(time units) The period of time that forecast results are retained.
After a forecast expires, the results are deleted. The default value is 14 days.
If set to a value of `0`, the forecast is never automatically deleted.
For more information about time units, see <<time-units>>.
[[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].
[[ml-forecast-example]]
==== {api-examples-title}

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

@ -15,6 +15,17 @@ Retrieves job results for one or more buckets.
`GET _ml/anomaly_detectors/<job_id>/results/buckets/<timestamp>`
[[ml-get-bucket-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, 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
{stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[ml-get-bucket-desc]]
==== {api-description-title}
@ -24,44 +35,44 @@ bucket.
[[ml-get-bucket-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(string) Identifier for the job
`timestamp`::
`<timestamp>` (Optional)::
(string) The timestamp of a single bucket result.
If you do not specify this optional parameter, the API returns information
If you do not specify this parameter, the API returns information
about all buckets.
[[ml-get-bucket-request-body]]
==== {api-request-body-title}
`anomaly_score`::
`anomaly_score` (Optional)::
(double) Returns buckets with anomaly scores greater or equal than this value.
`desc`::
`desc` (Optional)::
(boolean) If true, the buckets are sorted in descending order.
`end`::
`end` (Optional)::
(string) Returns buckets with timestamps earlier than this time.
`exclude_interim`::
`exclude_interim` (Optional)::
(boolean) If true, the output excludes interim results.
By default, interim results are included.
`expand`::
`expand` (Optional)::
(boolean) If true, the output includes anomaly records.
`page`::
`page` (Optional)::
`from`:::
(integer) Skips the specified number of buckets.
`size`:::
(integer) Specifies the maximum number of buckets to obtain.
`sort`::
`sort` (Optional)::
(string) Specifies the sort field for the requested buckets.
By default, the buckets are sorted by the `timestamp` field.
`start`::
`start` (Optional)::
(string) Returns buckets with timestamps after this time.
[[ml-get-bucket-results]]
@ -73,16 +84,6 @@ The API returns the following information:
(array) An array of bucket objects. For more information, see
<<ml-results-buckets,Buckets>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
[[ml-get-bucket-example]]
==== {api-examples-title}

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

@ -16,6 +16,13 @@ calendars.
`GET _ml/calendars/_all/events`
[[ml-get-calendar-event-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-calendar-event-desc]]
==== {api-description-title}
@ -25,22 +32,22 @@ calendars by using `_all`.
[[ml-get-calendar-event-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
[[ml-get-calendar-event-request-body]]
==== {api-request-body-title}
`end`::
`end` (Optional)::
(string) Specifies to get events with timestamps earlier than this time.
`from`::
`from` (Optional)::
(integer) Skips the specified number of events.
`size`::
`size` (Optional)::
(integer) Specifies the maximum number of events to obtain.
`start`::
`start` (Optional)::
(string) Specifies to get events with timestamps after this time.
[[ml-get-calendar-event-results]]
@ -52,13 +59,6 @@ The API returns the following information:
(array) An array of scheduled event resources.
For more information, see <<ml-event-resource>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-calendar-event-example]]
==== {api-examples-title}

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

@ -15,6 +15,13 @@ Retrieves configuration information for calendars.
`GET _ml/calendars/_all`
[[ml-get-calendar-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-calendar-desc]]
==== {api-description-title}
@ -24,17 +31,17 @@ You can get information for a single calendar or for all calendars by using
[[ml-get-calendar-path-parms]]
==== {api-path-parms-title}
`calendar_id`::
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
[[ml-get-calendar-request-body]]
==== {api-request-body-title}
`page`::
`page` (Optional)::
`from`:::
(integer) Skips the specified number of calendars.
`size`:::
`size` (Optional):::
(integer) Specifies the maximum number of calendars to obtain.
[[ml-get-calendar-results]]
@ -46,13 +53,6 @@ The API returns the following information:
(array) An array of calendar resources.
For more information, see <<ml-calendar-resource>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-calendar-example]]
==== {api-examples-title}

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

@ -15,26 +15,36 @@ Retrieves job results for one or more categories.
`GET _ml/anomaly_detectors/<job_id>/results/categories/<category_id>`
[[ml-get-category-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, 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. See {stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[ml-get-category-desc]]
==== {api-description-title}
For more information about categories, see
{stack-ov}/ml-configuring-categories.html[Categorizing Log Messages].
{stack-ov}/ml-configuring-categories.html[Categorizing log messages].
[[ml-get-category-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(string) Identifier for the job.
`category_id`::
(long) Identifier for the category. If you do not specify this optional parameter,
`<category_id>` (Optional)::
(long) Identifier for the category. If you do not specify this parameter,
the API returns information about all categories in the job.
[[ml-get-category-request-body]]
==== {api-request-body-title}
`page`::
`page` (Optional)::
`from`:::
(integer) Skips the specified number of categories.
`size`:::
@ -49,16 +59,6 @@ The API returns the following information:
(array) An array of category objects. For more information, see
<<ml-results-categories,Categories>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
[[ml-get-category-example]]
==== {api-examples-title}

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

@ -19,7 +19,14 @@ Retrieves usage information for {dfeeds}.
`GET _ml/datafeeds/_stats` +
`GET _ml/datafeeds/_all/_stats` +
`GET _ml/datafeeds/_all/_stats`
[[ml-get-datafeed-stats-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-datafeed-stats-desc]]
==== {api-description-title}
@ -37,7 +44,7 @@ IMPORTANT: This API returns a maximum of 10,000 {dfeeds}.
[[ml-get-datafeed-stats-path-parms]]
==== {api-path-parms-title}
`feed_id`::
`<feed_id>` (Optional)::
(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}.
@ -51,13 +58,6 @@ The API returns the following information:
(array) An array of {dfeed} count objects.
For more information, see <<ml-datafeed-counts>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-datafeed-stats-example]]
==== {api-examples-title}

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

@ -19,7 +19,14 @@ Retrieves configuration information for {dfeeds}.
`GET _ml/datafeeds/` +
`GET _ml/datafeeds/_all` +
`GET _ml/datafeeds/_all`
[[ml-get-datafeed-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-datafeed-desc]]
==== {api-description-title}
@ -34,7 +41,7 @@ IMPORTANT: This API returns a maximum of 10,000 {dfeeds}.
[[ml-get-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id`::
`<feed_id>` (Optional)::
(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}.
@ -48,13 +55,6 @@ The API returns the following information:
(array) An array of {dfeed} objects.
For more information, see <<ml-datafeed-resource>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-datafeed-example]]
==== {api-examples-title}

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

@ -15,6 +15,13 @@ Retrieves filters.
`GET _ml/filters/`
[[ml-get-filter-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-filter-desc]]
==== {api-description-title}
@ -24,16 +31,16 @@ You can get a single filter or all filters. For more information, see
[[ml-get-filter-path-parms]]
==== {api-path-parms-title}
`filter_id`::
`<filter_id>` (Optional)::
(string) Identifier for the filter.
[[ml-get-filter-query-parms]]
==== {api-query-parms-title}
`from`:::
`from` (Optional):::
(integer) Skips the specified number of filters.
`size`:::
`size` (Optional):::
(integer) Specifies the maximum number of filters to obtain.
[[ml-get-filter-results]]
@ -45,13 +52,6 @@ The API returns the following information:
(array) An array of filter resources.
For more information, see <<ml-filter-resource>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-filter-example]]
==== {api-examples-title}

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

@ -13,39 +13,49 @@ Retrieves job results for one or more influencers.
`GET _ml/anomaly_detectors/<job_id>/results/influencers`
[[ml-get-influencer-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, 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. See {stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[ml-get-influencer-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(string) Identifier for the job.
[[ml-get-influencer-request-body]]
==== {api-request-body-title}
`desc`::
`desc` (Optional)::
(boolean) If true, the results are sorted in descending order.
`end`::
`end` (Optional)::
(string) Returns influencers with timestamps earlier than this time.
`exclude_interim`::
`exclude_interim` (Optional)::
(boolean) If true, the output excludes interim results.
By default, interim results are included.
`influencer_score`::
`influencer_score` (Optional)::
(double) Returns influencers with anomaly scores greater or equal than this value.
`page`::
`page` (Optional)::
`from`:::
(integer) Skips the specified number of influencers.
`size`:::
(integer) Specifies the maximum number of influencers to obtain.
`sort`::
`sort` (Optional)::
(string) Specifies the sort field for the requested influencers.
By default the influencers are sorted by the `influencer_score` value.
`start`::
`start` (Optional)::
(string) Returns influencers with timestamps after this time.
[[ml-get-influencer-results]]
@ -57,16 +67,6 @@ The API returns the following information:
(array) An array of influencer objects.
For more information, see <<ml-results-influencers,Influencers>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
[[ml-get-influencer-example]]
==== {api-examples-title}

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

@ -17,7 +17,14 @@ Retrieves usage information for jobs.
`GET _ml/anomaly_detectors/_stats` +
`GET _ml/anomaly_detectors/_all/_stats` +
`GET _ml/anomaly_detectors/_all/_stats`
[[ml-get-job-stats-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-job-stats-desc]]
==== {api-description-title}
@ -32,7 +39,7 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
[[ml-get-job-stats-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Optional)::
(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.
@ -46,13 +53,6 @@ The API returns the following information:
(array) An array of job statistics objects.
For more information, see <<ml-jobstats,Job Statistics>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-job-stats-example]]
==== {api-examples-title}

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

@ -19,6 +19,13 @@ Retrieves configuration information for jobs.
`GET _ml/anomaly_detectors/_all`
[[ml-get-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-job-desc]]
==== {api-description-title}
@ -32,7 +39,7 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
[[ml-get-job-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id> (Optional)`::
(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.
@ -46,13 +53,6 @@ The API returns the following information:
(array) An array of job resources.
For more information, see <<ml-job-resource,Job Resources>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
[[ml-get-job-example]]
==== {api-examples-title}

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

@ -15,6 +15,15 @@ Returns defaults and limits used by machine learning.
`GET _ml/info`
[[get-ml-info-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, 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. See {stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[get-ml-info-desc]]
==== {api-description-title}
@ -23,15 +32,6 @@ 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.
[[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].
[[get-ml-info-example]]
==== {api-examples-title}

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

@ -18,6 +18,16 @@ bucket results of multiple jobs.
`GET _ml/anomaly_detectors/_all/results/overall_buckets`
[[ml-get-overall-buckets-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, 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. See {stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[ml-get-overall-buckets-desc]]
==== {api-description-title}
@ -46,37 +56,38 @@ overall buckets with a span equal to the largest job's `bucket_span`.
[[ml-get-overall-buckets-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(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.
[[ml-get-overall-buckets-request-body]]
==== {api-request-body-title}
`allow_no_jobs`::
`allow_no_jobs` (Optional)::
(boolean) If `false` and the `job_id` does not match any job an error will
be returned. The default value is `true`.
`bucket_span`::
`bucket_span` (Optional)::
(string) The span of the overall buckets. Must be greater or equal
to the largest job's `bucket_span`. Defaults to the largest job's `bucket_span`.
`end`::
`end` (Optional)::
(string) Returns overall buckets with timestamps earlier than this time.
`exclude_interim`::
`exclude_interim` (Optional)::
(boolean) If `true`, the output excludes interim overall buckets.
Overall buckets are interim if any of the job buckets within
the overall bucket interval are interim.
By default, interim results are included.
`overall_score`::
(double) Returns overall buckets with overall scores greater or equal than this value.
`overall_score` (Optional)::
(double) Returns overall buckets with overall scores greater or equal than
this value.
`start`::
`start` (Optional)::
(string) Returns overall buckets with timestamps after this time.
`top_n`::
`top_n` (Optional)::
(integer) The number of top job bucket scores to be used in the
`overall_score` calculation. The default value is `1`.
@ -89,16 +100,6 @@ The API returns the following information:
(array) An array of overall bucket objects. For more information, see
<<ml-results-overall-buckets,Overall Buckets>>.
[[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
{stack-ov}/security-privileges.html[Security Privileges] and
{stack-ov}/built-in-roles.html[Built-in Roles].
[[ml-get-overall-buckets-example]]
==== {api-examples-title}

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

@ -13,39 +13,49 @@ Retrieves anomaly records for a job.
`GET _ml/anomaly_detectors/<job_id>/results/records`
[[ml-get-record-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, 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. See {stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[ml-get-record-path-parms]]
==== {api-path-parms-title}
`job_id`::
`job_id` (Required)::
(string) Identifier for the job.
[[ml-get-record-request-body]]
==== {api-request-body-title}
`desc`::
`desc` (Optional)::
(boolean) If true, the results are sorted in descending order.
`end`::
`end` (Optional)::
(string) Returns records with timestamps earlier than this time.
`exclude_interim`::
`exclude_interim` (Optional)::
(boolean) If true, the output excludes interim results.
By default, interim results are included.
`page`::
`page` (Optional)::
`from`:::
(integer) Skips the specified number of records.
`size`:::
(integer) Specifies the maximum number of records to obtain.
`record_score`::
`record_score` (Optional)::
(double) Returns records with anomaly scores greater or equal than this value.
`sort`::
`sort` (Optional)::
(string) Specifies the sort field for the requested records.
By default, the records are sorted by the `anomaly_score` value.
`start`::
`start` (Optional)::
(string) Returns records with timestamps after this time.
[[ml-get-record-results]]
@ -57,16 +67,6 @@ The API returns the following information:
(array) An array of record objects. For more information, see
<<ml-results-records,Records>>.
[[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
{stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[ml-get-record-example]]
==== {api-examples-title}

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

@ -15,36 +15,43 @@ Retrieves information about model snapshots.
`GET _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
[[ml-get-snapshot-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id`::
`<job_id>` (Required)::
(string) Identifier for the job.
`snapshot_id`::
`<snapshot_id>` (Optional)::
(string) Identifier for the model snapshot. If you do not specify this
optional parameter, the API returns information about all model snapshots.
[[ml-get-snapshot-request-body]]
==== {api-request-body-title}
`desc`::
`desc` (Optional)::
(boolean) If true, the results are sorted in descending order.
`end`::
`end` (Optional)::
(date) Returns snapshots with timestamps earlier than this time.
`from`::
`from` (Optional)::
(integer) Skips the specified number of snapshots.
`size`::
`size` (Optional)::
(integer) Specifies the maximum number of snapshots to obtain.
`sort`::
`sort` (Optional)::
(string) Specifies the sort field for the requested snapshots.
By default, the snapshots are sorted by their timestamp.
`start`::
`start` (Optional)::
(string) Returns snapshots with timestamps after this time.
[[ml-get-snapshot-results]]
@ -56,13 +63,6 @@ The API returns the following information:
(array) An array of model snapshot objects. For more information, see
<<ml-snapshot-resource,Model Snapshots>>.
[[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
{stack-ov}/security-privileges.html[Security privileges].
[[ml-get-snapshot-example]]
==== {api-examples-title}

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

@ -15,34 +15,35 @@ A job can be opened and closed multiple times throughout its lifecycle.
`POST _ml/anomaly_detectors/{job_id}/_open`
[[ml-open-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[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.
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.
[[ml-open-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job
[[ml-open-job-request-body]]
==== {api-request-body-title}
`timeout`::
`timeout` (Optional)::
(time) Controls the time to wait until a job has opened.
The default value is 30 minutes.
[[ml-open-job-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].
[[ml-open-job-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Posts scheduled events in a calendar.
`POST _ml/calendars/<calendar_id>/events`
[[ml-post-calendar-event-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-post-calendar-event-desc]]
==== {api-description-title}
@ -22,23 +29,16 @@ of which must have a start time, end time, and description.
[[ml-post-calendar-event-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
[[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>>.
[[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
{stack-ov}/security-privileges.html[Security privileges].
`events` (Required)::
(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>>.
[[ml-post-calendar-event-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Sends data to an anomaly detection job for analysis.
`POST _ml/anomaly_detectors/<job_id>/_data`
[[ml-post-data-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-post-data-desc]]
==== {api-description-title}
@ -45,17 +52,17 @@ or a comma-separated list.
[[ml-post-data-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
[[ml-post-data-query-parms]]
==== {api-query-parms-title}
`reset_start`::
(string) Specifies the start of the bucket resetting range
`reset_start` (Optional)::
(string) Specifies the start of the bucket resetting range.
`reset_end`::
(string) Specifies the end of the bucket resetting range
`reset_end` (Optional)::
(string) Specifies the end of the bucket resetting range.
[[ml-post-data-request-body]]
==== {api-request-body-title}
@ -63,17 +70,11 @@ or a comma-separated list.
A sequence of one or more JSON documents containing the data to be analyzed.
Only whitespace characters are permitted in between the documents.
[[ml-post-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].
[[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:
The following example posts data from the `it_ops_new_kpi.json` file to the
`it_ops_new_kpi` job:
[source,js]
--------------------------------------------------
@ -82,8 +83,8 @@ $ curl -s -H "Content-type: application/json"
--data-binary @it_ops_new_kpi.json
--------------------------------------------------
When the data is sent, you receive information about the operational progress of the job.
For example:
When the data is sent, you receive information about the operational progress of
the job. For example:
[source,js]
----

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

@ -15,6 +15,13 @@ Previews a {dfeed}.
`GET _ml/datafeeds/<datafeed_id>/_preview`
[[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. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-preview-datafeed-desc]]
==== {api-description-title}
@ -22,30 +29,19 @@ 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.
IMPORTANT: When {es} {security-features} are enabled, the {dfeed} query is
previewed using the credentials of the user calling the preview {dfeed} API.
When the {dfeed} is started it runs the query using the roles of the last user
to create or update it. If the two sets of roles differ then the preview may
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.
[[ml-preview-datafeed-path-parms]]
==== {api-path-parms-title}
`datafeed_id` (required)::
(string) Identifier for the {dfeed}
[[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].
[[ml-preview-datafeed-security]]
==== Security Integration
When {es} {security-features} are enabled, the {dfeed} query is previewed using
the credentials of the user calling the preview {dfeed} API. When the {dfeed}
is started it runs the query using the roles of the last user to
create or update it. If the two sets of roles differ then the preview may
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.
`<datafeed_id>` (Required)::
(string) Identifier for the {dfeed}.
[[ml-preview-datafeed-example]]
==== {api-examples-title}

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

@ -13,22 +13,22 @@ Adds a job to a calendar.
`PUT _ml/calendars/<calendar_id>/jobs/<job_id>`
[[ml-put-calendar-job-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
(string) Identifier for the calendar.
`job_id` (required)::
(string) An identifier for the job. It can be a job identifier, a group name, or a
comma-separated list of jobs or groups.
[[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
{stack-ov}/security-privileges.html[Security Privileges].
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-put-calendar-job-path-parms]]
==== {api-path-parms-title}
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
`<job_id>` (Required)::
(string) An identifier for the job. It can be a job identifier, a group name,
or a comma-separated list of jobs or groups.
[[ml-put-calendar-job-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Instantiates a calendar.
`PUT _ml/calendars/<calendar_id>`
[[ml-put-calendar-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-put-calendar-desc]]
==== {api-description-title}
@ -22,22 +29,15 @@ For more information, see
[[ml-put-calendar-path-parms]]
==== {api-path-parms-title}
`calendar_id` (required)::
`<calendar_id>` (Required)::
(string) Identifier for the calendar.
[[ml-put-calendar-request-body]]
==== {api-request-body-title}
`description`::
`description` (Optional)::
(string) A description of the calendar.
[[ml-put-calendar-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].
[[ml-put-calendar-example]]
==== {api-examples-title}

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

@ -15,21 +15,34 @@ Instantiates a {dfeed}.
`PUT _ml/datafeeds/<feed_id>`
[[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. See
{stack-ov}/security-privileges.html[Security privileges].
[[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.
IMPORTANT: You must use {kib} or this API to create a {dfeed}. Do not put a {dfeed}
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.
[IMPORTANT]
====
* You must use {kib} or this API to create a {dfeed}. Do not put a
{dfeed} directly to the `.ml-config` index using the {es} index API. If {es}
{security-features} are enabled, do not give users `write` privileges on the
`.ml-config` index.
* 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.
====
[[ml-put-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
`<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.
@ -37,73 +50,58 @@ IMPORTANT: You must use {kib} or this API to create a {dfeed}. Do not put a {df
[[ml-put-datafeed-request-body]]
==== {api-request-body-title}
`aggregations`::
`aggregations` (Optional)::
(object) If set, the {dfeed} performs aggregation searches.
For more information, see <<ml-datafeed-resource>>.
`chunking_config`::
`chunking_config` (Optional)::
(object) Specifies how data searches are split into time chunks.
See <<ml-datafeed-chunking-config>>.
`delayed_data_check_config`::
`delayed_data_check_config` (Optional)::
(object) Specifies whether the data feed checks for missing data and
the size of the window. See
<<ml-datafeed-delayed-data-check-config>>.
`frequency`::
`frequency` (Optional)::
(time units) The interval at which scheduled queries are made while the {dfeed}
runs in real time. The default value is either the bucket span for short
bucket spans, or, for longer bucket spans, a sensible fraction of the bucket
span. For example: `150s`.
`indices` (required)::
`indices` (Required)::
(array) An array of index names. Wildcards are supported. For example:
`["it_ops_metrics", "server*"]`.
`job_id` (required)::
`job_id` (Required)::
(string) A numerical character string that uniquely identifies the job.
`query`::
`query` (Optional)::
(object) The {es} query domain-specific language (DSL). This value
corresponds to the query object in an {es} search POST body. All the
options that are supported by {Es} can be used, as this object is
passed verbatim to {es}. By default, this property has the following
value: `{"match_all": {"boost": 1}}`.
`query_delay`::
`query_delay` (Optional)::
(time units) The number of seconds behind real time that data is queried. For
example, if data from 10:04 a.m. might not be searchable in {es} until
10:06 a.m., set this property to 120 seconds. The default value is `60s`.
`script_fields`::
`script_fields` (Optional)::
(object) Specifies scripts that evaluate custom expressions and returns
script fields to the {dfeed}.
The <<ml-detectorconfig,detector configuration objects>> in a job can contain
functions that use these script fields.
For more information,
functions that use these script fields. For more information,
see {ref}/search-request-script-fields.html[Script Fields].
`scroll_size`::
`scroll_size` (Optional)::
(unsigned integer) The `size` parameter that is used in {es} searches.
The default value is `1000`.
For more information about these properties,
see <<ml-datafeed-resource>>.
[[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].
[[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.
[[ml-put-datafeed-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Instantiates a filter.
`PUT _ml/filters/<filter_id>`
[[ml-put-filter-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-put-filter-desc]]
==== {api-description-title}
@ -23,28 +30,21 @@ the `custom_rules` property of <<ml-detectorconfig,detector configuration object
[[ml-put-filter-path-parms]]
==== {api-path-parms-title}
`filter_id` (required)::
`<filter_id>` (Required)::
(string) Identifier for the filter.
[[ml-put-filter-request-body]]
==== {api-request-body-title}
`description`::
`description` (Optional)::
(string) A description of the filter.
`items`::
`items` (Required)::
(array of strings) The items of the filter.
A wildcard `*` can be used at the beginning
or the end of an item. Up to 10000 items
are allowed in each filter.
[[ml-put-filter-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].
[[ml-put-filter-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Instantiates a job.
`PUT _ml/anomaly_detectors/<job_id>`
[[ml-put-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-put-job-desc]]
==== {api-description-title}
@ -24,7 +31,7 @@ IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
[[ml-put-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
`<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.
@ -32,61 +39,54 @@ IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
[[ml-put-job-request-body]]
==== {api-request-body-title}
`analysis_config`::
`analysis_config` (Required)::
(object) The analysis configuration, which specifies how to analyze the data.
See <<ml-analysisconfig, analysis configuration objects>>.
`analysis_limits`::
`analysis_limits` (Optional)::
(object) Specifies runtime limits for the job. See
<<ml-apilimits,analysis limits>>.
`background_persist_interval`::
`background_persist_interval` (Optional)::
(time units) Advanced configuration option. The time between each periodic
persistence of the model. See <<ml-job-resource>>.
`custom_settings`::
`custom_settings` (Optional)::
(object) Advanced configuration option. Contains custom meta data about the
job. See <<ml-job-resource>>.
`data_description` (required)::
`data_description` (Required)::
(object) Describes the format of the input data. This object is required, but
it can be empty (`{}`). See <<ml-datadescription,data description objects>>.
`description`::
`description` (Optional)::
(string) A description of the job.
`groups`::
`groups` (Optional)::
(array of strings) A list of job groups. See <<ml-job-resource>>.
`model_plot_config`::
`model_plot_config` (Optional)::
(object) Advanced configuration option. Specifies to store model information
along with the results. This adds overhead to the performance of the system
and is not feasible for jobs with many entities, see <<ml-apimodelplotconfig>>.
`model_snapshot_retention_days`::
`model_snapshot_retention_days` (Optional)::
(long) The time in days that model snapshots are retained for the job.
Older snapshots are deleted. The default value is `1`, which means snapshots
are retained for one day (twenty-four hours).
`renormalization_window_days`::
`renormalization_window_days` (Optional)::
(long) Advanced configuration option. The period over which adjustments to the
score are applied, as new data is seen. See <<ml-job-resource>>.
`results_index_name`::
`results_index_name` (Optional)::
(string) A text string that affects the name of the {ml} results index. The
default value is `shared`, which generates an index named `.ml-anomalies-shared`.
`results_retention_days`::
`results_retention_days` (Optional)::
(long) Advanced configuration option. The number of days for which job results
are retained. See <<ml-job-resource>>.
[[ml-put-job-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].
[[ml-put-job-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Reverts to a specific snapshot.
`POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_revert`
[[ml-revert-snapshot-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-revert-snapshot-desc]]
==== {api-description-title}
@ -29,16 +36,16 @@ IMPORTANT: Before you revert to a saved snapshot, you must close the job.
[[ml-revert-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
`snapshot_id` (required)::
(string) Identifier for the model snapshot
`<snapshot_id>` (Required)::
(string) Identifier for the model snapshot.
[[ml-revert-snapshot-request-body]]
==== {api-request-body-title}
`delete_intervening_results`::
`delete_intervening_results` (Optional)::
(boolean) If true, deletes the results in the time period between the
latest results and the time of the reverted snapshot. It also resets the
model to accept records for this time period. The default value is false.
@ -47,13 +54,6 @@ 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.
[[ml-revert-snapshot-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].
[[ml-revert-snapshot-example]]
==== {api-examples-title}

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

@ -26,6 +26,13 @@ POST /_ml/set_upgrade_mode?enabled=false&timeout=10m
`POST _ml/set_upgrade_mode`
[[ml-set-upgrade-mode-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-set-upgrade-mode-desc]]
==== {api-description-title}
@ -54,20 +61,13 @@ IMPORTANT: No new {ml} jobs can be opened while the `upgrade_mode` setting is
[[ml-set-upgrade-mode-query-parms]]
==== {api-query-parms-title}
`enabled`::
`enabled` (Optional)::
(boolean) When `true`, this enables `upgrade_mode`. Defaults to `false`
`timeout`::
`timeout` (Optional)::
(time) The time to wait for the request to be completed.
The default value is 30 seconds.
[[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].
[[ml-set-upgrade-mode-example]]
==== {api-examples-title}

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

@ -17,6 +17,13 @@ A {dfeed} can be started and stopped multiple times throughout its lifecycle.
`POST _ml/datafeeds/<feed_id>/_start`
[[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. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-start-datafeed-desc]]
==== {api-description-title}
@ -58,41 +65,31 @@ 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.
IMPORTANT: 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.
[[ml-start-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) Identifier for the {dfeed}
`<feed_id>` (Required)::
(string) Identifier for the {dfeed}.
[[ml-start-datafeed-request-body]]
==== {api-request-body-title}
`end`::
`end` (Optional)::
(string) The time that the {dfeed} should end. This value is exclusive.
The default value is an empty string.
`start`::
`start` (Optional)::
(string) The time that the {dfeed} should begin. This value is inclusive.
The default value is an empty string.
`timeout`::
`timeout` (Optional)::
(time) Controls the amount of time to wait until a {dfeed} starts.
The default value is 20 seconds.
[[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].
[[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.
[[ml-start-datafeed-example]]
==== {api-examples-title}

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

@ -10,9 +10,6 @@
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.
[[ml-stop-datafeed-request]]
==== {api-request-title}
@ -22,9 +19,19 @@ A {dfeed} can be started and stopped multiple times throughout its lifecycle.
`POST _ml/datafeeds/_all/_stop`
[[ml-stop-datafeed-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-stop-datafeed-desc]]
==== {api-description-title}
A {dfeed} that is stopped ceases to retrieve data from {es}.
A {dfeed} can be started and stopped multiple times throughout its lifecycle.
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>`.
@ -32,27 +39,20 @@ comma-separated list of {dfeeds} or a wildcard expression. You can close all
[[ml-stop-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id`::
`<feed_id>` (Required)::
(string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
wildcard expression.
[[ml-stop-datafeed-request-body]]
==== {api-request-body-title}
`force`::
`force` (Optional)::
(boolean) If true, the {dfeed} is stopped forcefully.
`timeout`::
`timeout` (Optional)::
(time) Controls the amount of time to wait until a {dfeed} stops.
The default value is 20 seconds.
[[ml-stop-datafeed-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].
[[ml-stop-datafeed-example]]
==== {api-examples-title}

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

@ -15,61 +15,72 @@ Updates certain properties of a {dfeed}.
`POST _ml/datafeeds/<feed_id>/_update`
[[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. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-update-datafeed-desc]]
==== {api-description-title}
NOTE: If you update the `delayed_data_check_config` property, you must stop and
If you update the `delayed_data_check_config` property, you must stop and
start the {dfeed} for the change to be applied.
IMPORTANT: 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.
[[ml-update-datafeed-path-parms]]
==== {api-path-parms-title}
`feed_id` (required)::
(string) Identifier for the {dfeed}
`<feed_id>` (Required)::
(string) Identifier for the {dfeed}.
[[ml-update-datafeed-request-body]]
==== {api-request-body-title}
The following properties can be updated after the {dfeed} is created:
`aggregations`::
`aggregations` (Optional)::
(object) If set, the {dfeed} performs aggregation searches.
For more information, see <<ml-datafeed-resource>>.
`chunking_config`::
`chunking_config` (Optional)::
(object) Specifies how data searches are split into time chunks.
See <<ml-datafeed-chunking-config>>.
`delayed_data_check_config`::
`delayed_data_check_config` (Optional)::
(object) Specifies whether the data feed checks for missing data and
the size of the window. See <<ml-datafeed-delayed-data-check-config>>.
`frequency`::
`frequency` (Optional)::
(time units) The interval at which scheduled queries are made while the
{dfeed} runs in real time. The default value is either the bucket span for short
bucket spans, or, for longer bucket spans, a sensible fraction of the bucket
span. For example: `150s`.
`indices`::
`indices` (Optional)::
(array) An array of index names. Wildcards are supported. For example:
`["it_ops_metrics", "server*"]`.
`job_id`::
`job_id` (Optional)::
(string) A numerical character string that uniquely identifies the job.
`query`::
`query` (Optional)::
(object) The {es} query domain-specific language (DSL). This value
corresponds to the query object in an {es} search POST body. All the
options that are supported by {es} can be used, as this object is
passed verbatim to {es}. By default, this property has the following
value: `{"match_all": {"boost": 1}}`.
`query_delay`::
`query_delay` (Optional)::
(time units) The number of seconds behind real-time that data is queried. For
example, if data from 10:04 a.m. might not be searchable in {es} until
10:06 a.m., set this property to 120 seconds. The default value is `60s`.
`script_fields`::
`script_fields` (Optional)::
(object) Specifies scripts that evaluate custom expressions and returns
script fields to the {dfeed}.
The <<ml-detectorconfig,detector configuration objects>> in a job can contain
@ -77,27 +88,13 @@ The following properties can be updated after the {dfeed} is created:
For more information,
see {ref}/search-request-script-fields.html[Script Fields].
`scroll_size`::
`scroll_size` (Optional)::
(unsigned integer) The `size` parameter that is used in {es} searches.
The default value is `1000`.
For more information about these properties,
see <<ml-datafeed-resource>>.
[[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].
[[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.
[[ml-update-datafeed-example]]
==== {api-examples-title}

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

@ -13,35 +13,36 @@ Updates the description of a filter, adds items, or removes items.
`POST _ml/filters/<filter_id>/_update`
[[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`::
(string) A description for the filter. See <<ml-filter-resource>>.
`add_items`::
(array of strings) The items to add to the filter.
`remove_items`::
(array of strings) The items to remove from the filter.
[[ml-update-filter-prereqs]]
==== {api-prereq-title}
You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-update-filter-path-parms]]
==== {api-path-parms-title}
`<filter_id>` (Required)::
(string) Identifier for the filter.
[[ml-update-filter-request-body]]
==== {api-request-body-title}
`description` (Optional)::
(string) A description for the filter. See <<ml-filter-resource>>.
`add_items` (Optional)::
(array of strings) The items to add to the filter.
`remove_items` (Optional)::
(array of strings) The items to remove from the filter.
[[ml-update-filter-example]]
==== {api-examples-title}
You can change the description, add and remove items to the `safe_domains` filter as follows:
You can change the description, add and remove items to the `safe_domains`
filter as follows:
[source,js]
--------------------------------------------------

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

@ -13,11 +13,19 @@ Updates certain properties of a job.
`POST _ml/anomaly_detectors/<job_id>/_update`
[[ml-update-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-update-job-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
[[ml-update-job-request-body]]
==== {api-request-body-title}
@ -88,13 +96,6 @@ A detector update object has the following properties:
No other detector property can be updated.
[[ml-update-job-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].
[[ml-update-job-example]]
==== {api-examples-title}

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

@ -13,37 +13,38 @@ Updates certain properties of a snapshot.
`POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_update`
[[ml-update-snapshot-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-update-snapshot-path-parms]]
==== {api-path-parms-title}
`job_id` (required)::
(string) Identifier for the job
`<job_id>` (Required)::
(string) Identifier for the job.
`snapshot_id` (required)::
(string) Identifier for the model snapshot
`<snapshot_id>` (Required)::
(string) Identifier for the model snapshot.
[[ml-update-snapshot-request-body]]
==== {api-request-body-title}
The following properties can be updated after the model snapshot is created:
`description`::
(string) An optional description of the model snapshot. For example,
`description` (Optional)::
(string) A description of the model snapshot. For example,
"Before black friday".
`retain`::
`retain` (Optional)::
(boolean) If true, this snapshot will not be deleted during automatic cleanup
of snapshots older than `model_snapshot_retention_days`.
Note that this snapshot will still be deleted when the job is deleted.
The default value is false.
[[ml-update-snapshot-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].
[[ml-update-snapshot-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Validates detector configuration information.
`POST _ml/anomaly_detectors/_validate/detector`
[[ml-valid-detector-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-valid-detector-desc]]
==== {api-description-title}
@ -25,13 +32,6 @@ before you create a job.
For a list of the properties that you can specify in the body of this API,
see <<ml-detectorconfig,detector configuration objects>>.
[[ml-valid-detector-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].
[[ml-valid-detector-example]]
==== {api-examples-title}

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

@ -13,6 +13,13 @@ Validates job configuration information.
`POST _ml/anomaly_detectors/_validate`
[[ml-valid-job-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].
[[ml-valid-job-desc]]
==== {api-description-title}
@ -25,13 +32,6 @@ create the job.
For a list of the properties that you can specify in the body of this API,
see <<ml-job-resource,Job Resources>>.
[[ml-valid-job-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].
[[ml-valid-job-example]]
==== {api-examples-title}