elasticsearch/docs/java-rest/high-level/ml/post-data.asciidoc

[[java-rest-high-x-pack-ml-post-data]]
=== Post Data API

The Post Data API provides the ability to post data to an open
 {ml} job in the cluster.
It accepts a `PostDataRequest` object and responds
with a `PostDataResponse` object.

[[java-rest-high-x-pack-ml-post-data-request]]
==== Post Data Request

A `PostDataRequest` object gets created with an existing non-null `jobId`
and the `XContentType` being sent. Individual docs can be added
incrementally via the `PostDataRequest.JsonBuilder#addDoc` method.
These are then serialized and sent in bulk when passed to the `PostDataRequest`.

Alternatively, the serialized bulk content can be set manually, along with its `XContentType`
through one of the other `PostDataRequest` constructors.

Only `XContentType.JSON` and `XContentType.SMILE` are supported.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-request]
--------------------------------------------------
<1> Create a new `PostDataRequest.JsonBuilder` object for incrementally adding documents
<2> Add a new document as a `Map<String, Object>` object
<3> Add a new document as a serialized JSON formatted String.
<4> Constructing a new request referencing an opened `jobId`, and a JsonBuilder

==== Optional Arguments

The following arguments are optional.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-request-options]
--------------------------------------------------
<1> Set the start of the bucket resetting time
<2> Set the end of the bucket resetting time

[[java-rest-high-x-pack-ml-post-data-execution]]
==== Execution

The request can be executed through the `MachineLearningClient` contained
in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-execute]
--------------------------------------------------

[[java-rest-high-x-pack-ml-post-data-execution-async]]
==== Asynchronous Execution

The request can also be executed asynchronously:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-execute-async]
--------------------------------------------------
<1> The `PostDataRequest` to execute and the `ActionListener` to use when
the execution completes

The method does not block and returns immediately. The passed `ActionListener` is used
to notify the caller of completion. A typical `ActionListener` for `PostDataResponse` may
look like

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-listener]
--------------------------------------------------
<1> `onResponse` is called back when the action is completed successfully
<2> `onFailure` is called back when some unexpected error occurs

[[java-rest-high-x-pack-ml-post-data-response]]
==== Post Data Response

A `PostDataResponse` contains current data processing statistics.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-post-data-response]
--------------------------------------------------
<1> `getDataCounts()` a `DataCounts` object containing the current
data processing counts.