162 lines
5.8 KiB
Plaintext
162 lines
5.8 KiB
Plaintext
[[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 `PutJobRequest` 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
|