107 lines
5.0 KiB
Plaintext
107 lines
5.0 KiB
Plaintext
[[java-rest-high-x-pack-ml-get-overall-buckets]]
|
|
=== Get Overall Buckets API
|
|
|
|
The Get Overall Buckets API retrieves overall bucket results that
|
|
summarize the bucket results of multiple jobs.
|
|
It accepts a `GetOverallBucketsRequest` object and responds
|
|
with a `GetOverallBucketsResponse` object.
|
|
|
|
[[java-rest-high-x-pack-ml-get-overall-buckets-request]]
|
|
==== Get Overall Buckets Request
|
|
|
|
A `GetOverallBucketsRequest` object gets created with one or more `jobId`.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-request]
|
|
--------------------------------------------------
|
|
<1> Constructing a new request referencing job IDs `jobId1` and `jobId2`.
|
|
|
|
==== Optional Arguments
|
|
The following arguments are optional:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-bucket-span]
|
|
--------------------------------------------------
|
|
<1> The span of the overall buckets. Must be greater or equal to the jobs' largest `bucket_span`.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-end]
|
|
--------------------------------------------------
|
|
<1> Overall buckets with timestamps earlier than this time will be returned.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-exclude-interim]
|
|
--------------------------------------------------
|
|
<1> If `true`, interim results will be excluded. Overall buckets are interim if any of the job buckets
|
|
within the overall bucket interval are interim. Defaults to `false`.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-overall-score]
|
|
--------------------------------------------------
|
|
<1> Overall buckets with overall scores greater or equal than this value will be returned.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-start]
|
|
--------------------------------------------------
|
|
<1> Overall buckets with timestamps on or after this time will be returned.
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-top-n]
|
|
--------------------------------------------------
|
|
<1> The number of top job bucket scores to be used in the `overall_score` calculation. Defaults to `1`.
|
|
|
|
[[java-rest-high-x-pack-ml-get-overall-buckets-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-get-overall-buckets-execute]
|
|
--------------------------------------------------
|
|
|
|
[[java-rest-high-x-pack-ml-get-overall-buckets-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-get-overall-buckets-execute-async]
|
|
--------------------------------------------------
|
|
<1> The `GetOverallBucketsRequest` 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 with the `onResponse` method
|
|
if the execution is successful or the `onFailure` method if the execution
|
|
failed.
|
|
|
|
A typical listener for `GetBucketsResponse` looks like:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-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-get-overall-buckets-response]]
|
|
==== Get Overall Buckets Response
|
|
|
|
The returned `GetOverallBucketsResponse` contains the requested buckets:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-overall-buckets-response]
|
|
--------------------------------------------------
|
|
<1> The count of overall buckets that were matched
|
|
<2> The overall buckets retrieved |