mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
[ML] Add high level REST client docs for ML put job endpoint (#32843)
Relates #29827 Relates #32726
This commit is contained in:
David Roberts
GitHub
parent
0158b59a5a
commit
c985f500f4
5 changed files with 326 additions and 18 deletions
161
docs/java-rest/high-level/ml/put_job.asciidoc
Normal file
161
docs/java-rest/high-level/ml/put_job.asciidoc
Normal file
|
|
@ -0,0 +1,161 @@
|
|||
[[java-rest-high-x-pack-ml-put-job]]
|
||||
=== Put Job API
|
||||
|
||||
The Put Job API can be used to create a new {ml} job
|
||||
in the cluster. The API accepts a `PutJobRequest` object
|
||||
as a request and returns a `PutJobResponse`.
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-request]]
|
||||
==== Put Job Request
|
||||
|
||||
A `PutJobRequest` requires the following argument:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-request]
|
||||
--------------------------------------------------
|
||||
<1> The configuration of the {ml} job to create as a `Job`
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-config]]
|
||||
==== Job Configuration
|
||||
|
||||
The `Job` object contains all the details about the {ml} job
|
||||
configuration.
|
||||
|
||||
A `Job` requires the following arguments:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-config]
|
||||
--------------------------------------------------
|
||||
<1> The job ID
|
||||
<2> An analysis configuration
|
||||
<3> A data description
|
||||
<4> Optionally, a human-readable description
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-analysis-config]]
|
||||
==== Analysis Configuration
|
||||
|
||||
The analysis configuration of the {ml} job is defined in the `AnalysisConfig`.
|
||||
`AnalysisConfig` reflects all the configuration
|
||||
settings that can be defined using the REST API.
|
||||
|
||||
Using the REST API, we could define this analysis configuration:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
"analysis_config" : {
|
||||
"bucket_span" : "10m",
|
||||
"detectors" : [
|
||||
{
|
||||
"detector_description" : "Sum of total",
|
||||
"function" : "sum",
|
||||
"field_name" : "total"
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
Using the `AnalysisConfig` object and the high level REST client, the list
|
||||
of detectors must be built first.
|
||||
|
||||
An example of building a `Detector` instance is as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-detector]
|
||||
--------------------------------------------------
|
||||
<1> The function to use
|
||||
<2> The field to apply the function to
|
||||
<3> Optionally, a human-readable description
|
||||
|
||||
Then the same configuration would be:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-analysis-config]
|
||||
--------------------------------------------------
|
||||
<1> Create a list of detectors
|
||||
<2> Pass the list of detectors to the analysis config builder constructor
|
||||
<3> The bucket span
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-data-description]]
|
||||
==== Data Description
|
||||
|
||||
After defining the analysis config, the next thing to define is the
|
||||
data description, using a `DataDescription` instance. `DataDescription`
|
||||
reflects all the configuration settings that can be defined using the
|
||||
REST API.
|
||||
|
||||
Using the REST API, we could define this metrics configuration:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
"data_description" : {
|
||||
"time_field" : "timestamp"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
Using the `DataDescription` object and the high level REST client, the same
|
||||
configuration would be:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-data-description]
|
||||
--------------------------------------------------
|
||||
<1> The time field
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-execution]]
|
||||
==== Execution
|
||||
|
||||
The Put Job API can be executed through a `MachineLearningClient`
|
||||
instance. Such an instance can be retrieved from a `RestHighLevelClient`
|
||||
using the `machineLearning()` method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-response]]
|
||||
==== Response
|
||||
|
||||
The returned `PutJobResponse` returns the full representation of
|
||||
the new {ml} job if it has been successfully created. This will
|
||||
contain the creation time and other fields initialized using
|
||||
default values:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-response]
|
||||
--------------------------------------------------
|
||||
<1> The creation time is a field that was not passed in the `Job` object in the request
|
||||
|
||||
[[java-rest-high-x-pack-ml-put-job-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
This request can be executed asynchronously:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The `PutMlJobRequest` to execute and the `ActionListener` to use when
|
||||
the execution completes
|
||||
|
||||
The asynchronous method does not block and returns immediately. Once it is
|
||||
completed the `ActionListener` is called back using the `onResponse` method
|
||||
if the execution successfully completed or using the `onFailure` method if
|
||||
it failed.
|
||||
|
||||
A typical listener for `PutJobResponse` looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-put-job-execute-listener]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument
|
||||
<2> Called in case of failure. The raised exception is provided as an argument
|
||||
|
|
@ -200,6 +200,14 @@ include::licensing/put-license.asciidoc[]
|
|||
include::licensing/get-license.asciidoc[]
|
||||
include::licensing/delete-license.asciidoc[]
|
||||
|
||||
== Machine Learning APIs
|
||||
|
||||
The Java High Level REST Client supports the following Machine Learning APIs:
|
||||
|
||||
* <<java-rest-high-x-pack-ml-put-job>>
|
||||
|
||||
include::ml/put_job.asciidoc[]
|
||||
|
||||
== Migration APIs
|
||||
|
||||
The Java High Level REST Client supports the following Migration APIs:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue