OpenSearch/docs/java-rest/high-level/ml/put-job.asciidoc

[[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