Skip to content

[DOCS] Updates terms in anomaly detection job APIs #44839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 25, 2019
Merged

[DOCS] Updates terms in anomaly detection job APIs #44839

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions docs/java-rest/high-level/ml/close-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@
:response: CloseJobResponse
--
[id="{upid}-{api}"]
=== Close Job API
=== Close {anomaly-job} API

The Close Job API provides the ability to close {ml} jobs in the cluster.
It accepts a +{request}+ object and responds
with a +{response}+ object.
Closes {anomaly-jobs} in the cluster. It accepts a +{request}+ object and responds with a +{response}+ object.

[id="{upid}-{api}-request"]
==== Close Job Request
==== Close {anomaly-job} request

A +{request}+ object gets created with an existing non-null `jobId`.

Expand All @@ -28,7 +26,7 @@ which has not responded to its initial close request.
execution should wait for the job to be closed.

[id="{upid}-{api}-response"]
==== Close Job Response
==== Close {anomaly-job} response

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
Expand Down
25 changes: 15 additions & 10 deletions docs/java-rest/high-level/ml/delete-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@
:response: AcknowledgedResponse
--
[id="{upid}-{api}"]
=== Delete Job API
=== Delete {anomaly-job} API

Deletes an {anomaly-job} that exists in the cluster.

[id="{upid}-{api}-request"]
==== Delete Job Request
==== Delete {anomaly-job} request

A +{request}+ object requires a non-null `jobId` and can optionally set `force`.

Expand All @@ -17,7 +19,7 @@ include-tagged::{doc-tests-file}[{api}-request]
---------------------------------------------------
<1> Constructing a new request referencing an existing `jobId`

==== Optional Arguments
==== Optional arguments

The following arguments are optional:

Expand All @@ -33,21 +35,24 @@ Defaults to `false`.
---------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-wait-for-completion]
---------------------------------------------------
<1> Use to set whether the request should wait until the operation has completed before returning.
Defaults to `true`.
<1> Use to set whether the request should wait until the operation has completed
before returning. Defaults to `true`.


[id="{upid}-{api}-response"]
==== Delete Job Response
==== Delete {anomaly-job} response

The returned +{response}+ object indicates the acknowledgement of the job deletion or
the deletion task depending on whether the request was set to wait for completion:
The returned +{response}+ object indicates the acknowledgement of the job
deletion or the deletion task depending on whether the request was set to wait
for completion:

["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
include-tagged::{doc-tests-file}[{api}-response]
---------------------------------------------------
<1> whether was job deletion was acknowledged or not; will be `null` when set not to wait for completion
<2> the id of the job deletion task; will be `null` when set to wait for completion
<1> whether was job deletion was acknowledged or not; will be `null` when set
Copy link
Contributor

@droberts195 droberts195 Jul 25, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not a problem introduced by this PR, but there's a spurious "was" between "whether" and "job".

Also most of these callout notes begin with capital letters but <1> and <2> here don't.

And finally <2> contains "id" in lowercase, and elsewhere you've been changing these to "ID" in uppercase.

Since the PR is green feel free to merge as-is and leave these typos for a future PR if you prefer.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @droberts195 I've put those fixes in #44865

not to wait for completion
<2> the id of the job deletion task; will be `null` when set to wait for
completion

include::../execution.asciidoc[]
11 changes: 5 additions & 6 deletions docs/java-rest/high-level/ml/open-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,13 @@
:response: OpenJobResponse
--
[id="{upid}-{api}"]
=== Open Job API
=== Open {anomaly-job} API

The Open Job API provides the ability to open {ml} jobs in the cluster.
It accepts a +{request}+ object and responds
with a +{response}+ object.
Opens {anomaly-jobs} in the cluster. It accepts a +{request}+ object and
responds with a +{response}+ object.

[id="{upid}-{api}-request"]
==== Open Job Request
==== Open {anomaly-job} request

An +{request}+ object gets created with an existing non-null `jobId`.

Expand All @@ -24,7 +23,7 @@ include-tagged::{doc-tests-file}[{api}-request]
execution should wait for the job to be opened.

[id="{upid}-{api}-response"]
==== Open Job Response
==== Open {anomaly-job} response

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
Expand Down
19 changes: 9 additions & 10 deletions docs/java-rest/high-level/ml/put-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,26 @@
:response: PutJobResponse
--
[id="{upid}-{api}"]
=== Put Job API
=== Put {anomaly-job} API

The Put Job API can be used to create a new {ml} job
in the cluster. The API accepts a +{request}+ object
Creates a new {anomaly-job} in the cluster. The API accepts a +{request}+ object
as a request and returns a +{response}+.

[id="{upid}-{api}-request"]
==== Put Job Request
==== Put {anomaly-job} request

A +{request}+ requires the following argument:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------
<1> The configuration of the {ml} job to create as a `Job`
<1> The configuration of the {anomaly-job} to create as a `Job`

[id="{upid}-{api}-config"]
==== Job Configuration
==== Job configuration

The `Job` object contains all the details about the {ml} job
The `Job` object contains all the details about the {anomaly-job}
configuration.

A `Job` requires the following arguments:
Expand All @@ -39,9 +38,9 @@ include-tagged::{doc-tests-file}[{api}-config]
<4> Optionally, a human-readable description

[id="{upid}-{api}-analysis-config"]
==== Analysis Configuration
==== Analysis configuration

The analysis configuration of the {ml} job is defined in the `AnalysisConfig`.
The analysis configuration of the {anomaly-job} is defined in the `AnalysisConfig`.
`AnalysisConfig` reflects all the configuration
settings that can be defined using the REST API.

Expand Down Expand Up @@ -86,7 +85,7 @@ include-tagged::{doc-tests-file}[{api}-analysis-config]
<3> The bucket span

[id="{upid}-{api}-data-description"]
==== Data Description
==== Data description

After defining the analysis config, the next thing to define is the
data description, using a `DataDescription` instance. `DataDescription`
Expand Down
14 changes: 7 additions & 7 deletions docs/reference/ml/anomaly-detection/apis/close-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
[role="xpack"]
[testenv="platinum"]
[[ml-close-job]]
=== Close jobs API
=== Close {anomaly-jobs} API
++++
<titleabbrev>Close jobs</titleabbrev>
++++

Closes one or more jobs.
Closes one or more {anomaly-jobs}.
A job can be opened and closed multiple times throughout its lifecycle.

A closed job cannot receive data or perform analysis
Expand All @@ -31,9 +31,9 @@ operations, but you can still explore and navigate results.
[[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
by using `_all` or by specifying `*` as the `<job_id>`.
You can close multiple {anomaly-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 by using `_all` or by specifying `*` as the `<job_id>`.

When you close a job, it runs housekeeping tasks such as pruning the model history,
flushing buffers, calculating final results and persisting the model snapshots.
Expand All @@ -58,8 +58,8 @@ results the job might have recently produced or might produce in the future.
==== {api-path-parms-title}

`<job_id>`::
(Required, string) Identifier for the job. It can be a job identifier, a group
name, or a wildcard expression.
(Required, string) Identifier for the {anomaly-job}. It can be a job
identifier, a group name, or a wildcard expression.

[[ml-close-job-query-parms]]
==== {api-query-parms-title}
Expand Down
14 changes: 7 additions & 7 deletions docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
[role="xpack"]
[testenv="platinum"]
[[ml-delete-job]]
=== Delete jobs API
=== Delete {anomaly-jobs} API
++++
<titleabbrev>Delete jobs</titleabbrev>
++++

Deletes an existing anomaly detection job.
Deletes an existing {anomaly-job}.

[[ml-delete-job-request]]
==== {api-request-title}
Expand All @@ -25,14 +25,14 @@ cluster privileges to use this API. See

All job configuration, model state and results are deleted.

IMPORTANT: Deleting a job must be done via this API only. Do not delete the
job directly from the `.ml-*` indices using the Elasticsearch delete document
IMPORTANT: Deleting an {anomaly-job} must be done via this API only. Do not
delete the job directly from the `.ml-*` indices using the {es} delete document
API. When {es} {security-features} are enabled, make sure no `write` privileges
are granted to anyone over the `.ml-*` indices.

Before you can delete a job, you must delete the {dfeeds} that are associated
with it. See <<ml-delete-datafeed,Delete {dfeeds-cap}>>. Unless the `force` parameter
is used the job must be closed before it can be deleted.
with it. See <<ml-delete-datafeed,Delete {dfeeds-cap}>>. Unless the `force`
parameter 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.
Expand All @@ -41,7 +41,7 @@ separated list.
==== {api-path-parms-title}

`<job_id>`::
(Required, string) Identifier for the job.
(Required, string) Identifier for the {anomaly-job}.

[[ml-delete-job-query-parms]]
==== {api-query-parms-title}
Expand Down
11 changes: 6 additions & 5 deletions docs/reference/ml/anomaly-detection/apis/open-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
[role="xpack"]
[testenv="platinum"]
[[ml-open-job]]
=== Open jobs API
=== Open {anomaly-jobs} API
++++
<titleabbrev>Open jobs</titleabbrev>
++++

Opens one or more jobs.
Opens one or more {anomaly-jobs}.

[[ml-open-job-request]]
==== {api-request-title}
Expand All @@ -23,8 +23,9 @@ Opens one or more jobs.
[[ml-open-job-desc]]
==== {api-description-title}

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.
An {anomaly-job} must be opened in order for it to be ready to receive and
analyze data. It can be opened and closed multiple times throughout its
lifecycle.

When you open a new job, it starts with an empty model.

Expand All @@ -36,7 +37,7 @@ data is received.
==== {api-path-parms-title}

`<job_id>`::
(Required, string) Identifier for the job
(Required, string) Identifier for the {anomaly-job}.

[[ml-open-job-request-body]]
==== {api-request-body-title}
Expand Down
4 changes: 1 addition & 3 deletions docs/reference/ml/anomaly-detection/apis/put-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,8 @@
[testenv="platinum"]
[[ml-put-job]]
=== Create {anomaly-jobs} API

[subs="attributes"]
++++
<titleabbrev>Create {anomaly-jobs}</titleabbrev>
<titleabbrev>Create jobs</titleabbrev>
++++

Instantiates an {anomaly-job}.
Expand Down