Skip to content

Commit 6f5daad

Browse files
benwtrentbenwtrent
authored
Feature/hlrc ml docs cleanup (#34316)
* HLRC: ML Add preview datafeed api * Changing deprecation handling for parser * Removing some duplication in docs, will address other APIs in another PR * HLRC: ML Cleanup docs * updating get datafeed stats docs
1 parent a9fa5f2 commit 6f5daad

26 files changed

+809
-1458
lines changed

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java‎

Lines changed: 375 additions & 356 deletions
Large diffs are not rendered by default.

‎docs/java-rest/high-level/ml/close-job.asciidoc‎

Lines changed: 16 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
1-
[[java-rest-high-x-pack-ml-close-job]]
1+
--
2+
:api: close-job
3+
:request: CloseJobRequest
4+
:response: CloseJobResponse
5+
--
6+
[id="{upid}-{api}"]
27
=== Close Job API
38

49
The Close Job API provides the ability to close {ml} jobs in the cluster.
5-
It accepts a `CloseJobRequest` object and responds
6-
with a `CloseJobResponse` object.
10+
It accepts a +{request}+ object and responds
11+
with a +{response}+ object.
712

8-
[[java-rest-high-x-pack-ml-close-job-request]]
13+
[id="{upid}-{api}-request"]
914
==== Close Job Request
1015

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

1318
["source","java",subs="attributes,callouts,macros"]
1419
--------------------------------------------------
15-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-request]
20+
include-tagged::{doc-tests-file}[{api}-request]
1621
--------------------------------------------------
1722
<1> Constructing a new request referencing existing job IDs
1823
<2> Optionally used to close a failed job, or to forcefully close a job
@@ -22,38 +27,14 @@ which has not responded to its initial close request.
2227
<4> Optionally setting the `timeout` value for how long the
2328
execution should wait for the job to be closed.
2429

25-
[[java-rest-high-x-pack-ml-close-job-execution]]
26-
==== Execution
27-
28-
The request can be executed through the `MachineLearningClient` contained
29-
in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
30+
[id="{upid}-{api}-response"]
31+
==== Close Job Response
3032

3133
["source","java",subs="attributes,callouts,macros"]
3234
--------------------------------------------------
33-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-execute]
35+
include-tagged::{doc-tests-file}[{api}-response]
3436
--------------------------------------------------
35-
<1> `isClosed()` from the `CloseJobResponse` indicates if the job was successfully
37+
<1> `isClosed()` from the +{response}+ indicates if the job was successfully
3638
closed or not.
3739

38-
[[java-rest-high-x-pack-ml-close-job-execution-async]]
39-
==== Asynchronous Execution
40-
41-
The request can also be executed asynchronously:
42-
43-
["source","java",subs="attributes,callouts,macros"]
44-
--------------------------------------------------
45-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-execute-async]
46-
--------------------------------------------------
47-
<1> The `CloseJobRequest` to execute and the `ActionListener` to use when
48-
the execution completes
49-
50-
The method does not block and returns immediately. The passed `ActionListener` is used
51-
to notify the caller of completion. A typical `ActionListener` for `CloseJobResponse` may
52-
look like
53-
54-
["source","java",subs="attributes,callouts,macros"]
55-
--------------------------------------------------
56-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-listener]
57-
--------------------------------------------------
58-
<1> `onResponse` is called back when the action is completed successfully
59-
<2> `onFailure` is called back when some unexpected error occurs
40+
include::../execution.asciidoc[]

‎docs/java-rest/high-level/ml/delete-calendar.asciidoc‎

Lines changed: 14 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,33 @@
1-
[[java-rest-high-x-pack-ml-delete-calendar]]
1+
--
2+
:api: delete-calendar
3+
:request: DeleteCalendarRequest
4+
:response: AcknowledgedResponse
5+
--
6+
[id="{upid}-{api}"]
27
=== Delete Calendar API
38
Delete a {ml} calendar.
4-
The API accepts a `DeleteCalendarRequest` and responds
5-
with a `AcknowledgedResponse` object.
9+
The API accepts a +{request}+ and responds
10+
with a +{response}+ object.
611

7-
[[java-rest-high-x-pack-ml-delete-calendar-request]]
12+
[id="{upid}-{api}-request"]
813
==== Delete Calendar Request
914

1015
A `DeleteCalendar` object requires a non-null `calendarId`.
1116

1217
["source","java",subs="attributes,callouts,macros"]
1318
---------------------------------------------------
14-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-request]
19+
include-tagged::{doc-tests-file}[{api}-request]
1520
---------------------------------------------------
1621
<1> Constructing a new request referencing an existing Calendar
1722

18-
[[java-rest-high-x-pack-ml-delete-calendar-response]]
23+
[id="{upid}-{api}-response"]
1924
==== Delete Calendar Response
2025

21-
The returned `AcknowledgedResponse` object indicates the acknowledgement of the request:
26+
The returned +{response}+ object indicates the acknowledgement of the request:
2227
["source","java",subs="attributes,callouts,macros"]
2328
---------------------------------------------------
24-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-response]
29+
include-tagged::{doc-tests-file}[{api}-response]
2530
---------------------------------------------------
2631
<1> `isAcknowledged` was the deletion request acknowledged or not
2732

28-
[[java-rest-high-x-pack-ml-delete-calendar-execution]]
29-
==== Execution
30-
The request can be executed through the `MachineLearningClient` contained
31-
in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
32-
33-
["source","java",subs="attributes,callouts,macros"]
34-
--------------------------------------------------
35-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-execute]
36-
--------------------------------------------------
37-
38-
[[java-rest-high-x-pack-ml-delete-calendar-async]]
39-
==== Delete Calendar Asynchronously
40-
41-
This request can also be made asynchronously.
42-
["source","java",subs="attributes,callouts,macros"]
43-
---------------------------------------------------
44-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-execute-async]
45-
---------------------------------------------------
46-
<1> The `DeleteCalendarRequest` to execute and the `ActionListener` to alert on completion or error.
47-
48-
The deletion request returns immediately. Once the request is completed, the `ActionListener` is
49-
called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
50-
making the request.
51-
52-
A typical listener for a `DeleteCalendarRequest` could be defined as follows:
53-
54-
["source","java",subs="attributes,callouts,macros"]
55-
---------------------------------------------------
56-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-listener]
57-
---------------------------------------------------
58-
<1> The action to be taken when it is completed
59-
<2> What to do when a failure occurs
33+
include::../execution.asciidoc[]

‎docs/java-rest/high-level/ml/delete-datafeed.asciidoc‎

Lines changed: 14 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,32 @@
1-
[[java-rest-high-x-pack-ml-delete-datafeed]]
1+
--
2+
:api: delete-datafeed
3+
:request: DeleteDatafeedRequest
4+
:response: AcknowledgedResponse
5+
--
6+
[id="{upid}-delete-datafeed"]
27
=== Delete Datafeed API
38

4-
[[java-rest-high-x-pack-machine-learning-delete-datafeed-request]]
9+
[id="{upid}-{api}-request"]
510
==== Delete Datafeed Request
611

7-
A `DeleteDatafeedRequest` object requires a non-null `datafeedId` and can optionally set `force`.
8-
Can be executed as follows:
12+
A +{request}+ object requires a non-null `datafeedId` and can optionally set `force`.
913

1014
["source","java",subs="attributes,callouts,macros"]
1115
---------------------------------------------------
12-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request]
16+
include-tagged::{doc-tests-file}[{api}-request]
1317
---------------------------------------------------
1418
<1> Use to forcefully delete a started datafeed;
1519
this method is quicker than stopping and deleting the datafeed.
1620
Defaults to `false`.
1721

18-
[[java-rest-high-x-pack-machine-learning-delete-datafeed-response]]
22+
include::../execution.asciidoc[]
23+
24+
[id="{upid}-{api}-response"]
1925
==== Delete Datafeed Response
2026

21-
The returned `AcknowledgedResponse` object indicates the acknowledgement of the request:
27+
The returned +{response}+ object indicates the acknowledgement of the request:
2228
["source","java",subs="attributes,callouts,macros"]
2329
---------------------------------------------------
24-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-response]
30+
include-tagged::{doc-tests-file}[{api}-response]
2531
---------------------------------------------------
2632
<1> `isAcknowledged` was the deletion request acknowledged or not
27-
28-
[[java-rest-high-x-pack-machine-learning-delete-datafeed-async]]
29-
==== Delete Datafeed Asynchronously
30-
31-
This request can also be made asynchronously.
32-
["source","java",subs="attributes,callouts,macros"]
33-
---------------------------------------------------
34-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request-async]
35-
---------------------------------------------------
36-
<1> The `DeleteDatafeedRequest` to execute and the `ActionListener` to alert on completion or error.
37-
38-
The deletion request returns immediately. Once the request is completed, the `ActionListener` is
39-
called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
40-
making the request.
41-
42-
A typical listener for a `DeleteDatafeedRequest` could be defined as follows:
43-
44-
["source","java",subs="attributes,callouts,macros"]
45-
---------------------------------------------------
46-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request-listener]
47-
---------------------------------------------------
48-
<1> The action to be taken when it is completed
49-
<2> What to do when a failure occurs

‎docs/java-rest/high-level/ml/delete-forecast.asciidoc‎

Lines changed: 18 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
1-
[[java-rest-high-x-pack-ml-delete-forecast]]
1+
--
2+
:api: delete-forecast
3+
:request: DeleteForecastRequest
4+
:response: AcknowledgedResponse
5+
--
6+
[id="{upid}-{api}"]
27
=== Delete Forecast API
38

49
The Delete Forecast API provides the ability to delete a {ml} job's
510
forecast in the cluster.
6-
It accepts a `DeleteForecastRequest` object and responds
7-
with an `AcknowledgedResponse` object.
11+
It accepts a +{request}+ object and responds
12+
with an +{response}+ object.
813

9-
[[java-rest-high-x-pack-ml-delete-forecast-request]]
14+
[id="{upid}-{api}-request"]
1015
==== Delete Forecast Request
1116

12-
A `DeleteForecastRequest` object gets created with an existing non-null `jobId`.
17+
A +{request}+ object gets created with an existing non-null `jobId`.
1318
All other fields are optional for the request.
1419

1520
["source","java",subs="attributes,callouts,macros"]
1621
--------------------------------------------------
17-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-request]
22+
include-tagged::{doc-tests-file}[{api}-request]
1823
--------------------------------------------------
1924
<1> Constructing a new request referencing an existing `jobId`
2025

@@ -24,55 +29,23 @@ The following arguments are optional.
2429

2530
["source","java",subs="attributes,callouts,macros"]
2631
--------------------------------------------------
27-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-request-options]
32+
include-tagged::{doc-tests-file}[{api}-request-options]
2833
--------------------------------------------------
2934
<1> Sets the specific forecastIds to delete, can be set to `_all` to indicate ALL forecasts for the given
3035
`jobId`
3136
<2> Set the timeout for the request to respond, default is 30 seconds
3237
<3> Set the `allow_no_forecasts` option. When `true` no error will be returned if an `_all`
33-
request finds no forecasts. It defaults to `true`
38+
request finds no forecasts. It defaults to `true`
3439

35-
[[java-rest-high-x-pack-ml-delete-forecast-execution]]
36-
==== Execution
37-
38-
The request can be executed through the `MachineLearningClient` contained
39-
in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
40-
41-
["source","java",subs="attributes,callouts,macros"]
42-
--------------------------------------------------
43-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-execute]
44-
--------------------------------------------------
45-
46-
[[java-rest-high-x-pack-ml-delete-forecast-execution-async]]
47-
==== Asynchronous Execution
48-
49-
The request can also be executed asynchronously:
50-
51-
["source","java",subs="attributes,callouts,macros"]
52-
--------------------------------------------------
53-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-execute-async]
54-
--------------------------------------------------
55-
<1> The `DeleteForecastRequest` to execute and the `ActionListener` to use when
56-
the execution completes
57-
58-
The method does not block and returns immediately. The passed `ActionListener` is used
59-
to notify the caller of completion. A typical `ActionListener` for `AcknowledgedResponse` may
60-
look like
61-
62-
["source","java",subs="attributes,callouts,macros"]
63-
--------------------------------------------------
64-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-listener]
65-
--------------------------------------------------
66-
<1> `onResponse` is called back when the action is completed successfully
67-
<2> `onFailure` is called back when some unexpected error occurs
68-
69-
[[java-rest-high-x-pack-ml-delete-forecast-response]]
40+
[id="{upid}-{api}-response"]
7041
==== Delete Forecast Response
7142

72-
An `AcknowledgedResponse` contains an acknowledgement of the forecast(s) deletion
43+
An +{response}+ contains an acknowledgement of the forecast(s) deletion
7344

7445
["source","java",subs="attributes,callouts,macros"]
7546
--------------------------------------------------
76-
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-response]
47+
include-tagged::{doc-tests-file}[{api}-response]
7748
--------------------------------------------------
7849
<1> `isAcknowledged()` indicates if the forecast was successfully deleted or not.
50+
51+
include::../execution.asciidoc[]

0 commit comments

Comments
 (0)