HLRC: Add ML get overall buckets API (#33297)

Relates #29827

Author: dimitris-athanasiou

client/rest-high-level/src/main/java/org/elasticsearch/client/MLRequestConverters.java

@@ -26,14 +26,15 @@
 import org.elasticsearch.client.RequestConverters.EndpointBuilder;
 import org.elasticsearch.client.ml.CloseJobRequest;
 import org.elasticsearch.client.ml.DeleteJobRequest;
+import org.elasticsearch.client.ml.FlushJobRequest;
 import org.elasticsearch.client.ml.GetBucketsRequest;
 import org.elasticsearch.client.ml.GetJobRequest;
 import org.elasticsearch.client.ml.GetJobStatsRequest;
+import org.elasticsearch.client.ml.GetOverallBucketsRequest;
 import org.elasticsearch.client.ml.GetRecordsRequest;
 import org.elasticsearch.client.ml.OpenJobRequest;
 import org.elasticsearch.client.ml.PutJobRequest;
 import org.elasticsearch.common.Strings;
-import org.elasticsearch.client.ml.FlushJobRequest;
 
 import java.io.IOException;
 
@@ -73,6 +74,23 @@ static Request getJob(GetJobRequest getJobRequest) {
         return request;
     }
 
+    static Request getJobStats(GetJobStatsRequest getJobStatsRequest) {
+        String endpoint = new EndpointBuilder()
+                .addPathPartAsIs("_xpack")
+                .addPathPartAsIs("ml")
+                .addPathPartAsIs("anomaly_detectors")
+                .addPathPart(Strings.collectionToCommaDelimitedString(getJobStatsRequest.getJobIds()))
+                .addPathPartAsIs("_stats")
+                .build();
+        Request request = new Request(HttpGet.METHOD_NAME, endpoint);
+
+        RequestConverters.Params params = new RequestConverters.Params(request);
+        if (getJobStatsRequest.isAllowNoJobs() != null) {
+            params.putParam("allow_no_jobs", Boolean.toString(getJobStatsRequest.isAllowNoJobs()));
+        }
+        return request;
+    }
+
     static Request openJob(OpenJobRequest openJobRequest) throws IOException {
         String endpoint = new EndpointBuilder()
                 .addPathPartAsIs("_xpack")
@@ -114,6 +132,19 @@ static Request deleteJob(DeleteJobRequest deleteJobRequest) {
         return request;
     }
 
+    static Request flushJob(FlushJobRequest flushJobRequest) throws IOException {
+        String endpoint = new EndpointBuilder()
+                .addPathPartAsIs("_xpack")
+                .addPathPartAsIs("ml")
+                .addPathPartAsIs("anomaly_detectors")
+                .addPathPart(flushJobRequest.getJobId())
+                .addPathPartAsIs("_flush")
+                .build();
+        Request request = new Request(HttpPost.METHOD_NAME, endpoint);
+        request.setEntity(createEntity(flushJobRequest, REQUEST_BODY_CONTENT_TYPE));
+        return request;
+    }
+
     static Request getBuckets(GetBucketsRequest getBucketsRequest) throws IOException {
         String endpoint = new EndpointBuilder()
                 .addPathPartAsIs("_xpack")
@@ -128,33 +159,17 @@ static Request getBuckets(GetBucketsRequest getBucketsRequest) throws IOExceptio
         return request;
     }
 
-    static Request flushJob(FlushJobRequest flushJobRequest) throws IOException {
-        String endpoint = new EndpointBuilder()
-            .addPathPartAsIs("_xpack")
-            .addPathPartAsIs("ml")
-            .addPathPartAsIs("anomaly_detectors")
-            .addPathPart(flushJobRequest.getJobId())
-            .addPathPartAsIs("_flush")
-            .build();
-        Request request = new Request(HttpPost.METHOD_NAME, endpoint);
-        request.setEntity(createEntity(flushJobRequest, REQUEST_BODY_CONTENT_TYPE));
-        return request;
-    }
-
-    static Request getJobStats(GetJobStatsRequest getJobStatsRequest) {
+    static Request getOverallBuckets(GetOverallBucketsRequest getOverallBucketsRequest) throws IOException {
         String endpoint = new EndpointBuilder()
-            .addPathPartAsIs("_xpack")
-            .addPathPartAsIs("ml")
-            .addPathPartAsIs("anomaly_detectors")
-            .addPathPart(Strings.collectionToCommaDelimitedString(getJobStatsRequest.getJobIds()))
-            .addPathPartAsIs("_stats")
-            .build();
+                .addPathPartAsIs("_xpack")
+                .addPathPartAsIs("ml")
+                .addPathPartAsIs("anomaly_detectors")
+                .addPathPart(Strings.collectionToCommaDelimitedString(getOverallBucketsRequest.getJobIds()))
+                .addPathPartAsIs("results")
+                .addPathPartAsIs("overall_buckets")
+                .build();
         Request request = new Request(HttpGet.METHOD_NAME, endpoint);
-
-        RequestConverters.Params params = new RequestConverters.Params(request);
-        if (getJobStatsRequest.isAllowNoJobs() != null) {
-            params.putParam("allow_no_jobs", Boolean.toString(getJobStatsRequest.isAllowNoJobs()));
-        }
+        request.setEntity(createEntity(getOverallBucketsRequest, REQUEST_BODY_CONTENT_TYPE));
         return request;
     }
 

client/rest-high-level/src/main/java/org/elasticsearch/client/MachineLearningClient.java

@@ -32,6 +32,8 @@
 import org.elasticsearch.client.ml.GetBucketsResponse;
 import org.elasticsearch.client.ml.GetJobRequest;
 import org.elasticsearch.client.ml.GetJobResponse;
+import org.elasticsearch.client.ml.GetOverallBucketsRequest;
+import org.elasticsearch.client.ml.GetOverallBucketsResponse;
 import org.elasticsearch.client.ml.GetRecordsRequest;
 import org.elasticsearch.client.ml.GetRecordsResponse;
 import org.elasticsearch.client.ml.OpenJobRequest;
@@ -136,6 +138,47 @@ public void getJobAsync(GetJobRequest request, RequestOptions options, ActionLis
             Collections.emptySet());
     }
 
+    /**
+     * Gets usage statistics for one or more Machine Learning jobs
+     *
+     * <p>
+     *     For additional info
+     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job-stats.html">Get Job stats docs</a>
+     * </p>
+     * @param request {@link GetJobStatsRequest} Request containing a list of jobId(s) and additional options
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return {@link GetJobStatsResponse} response object containing
+     * the {@link JobStats} objects and the number of jobs found
+     * @throws IOException when there is a serialization issue sending the request or receiving the response
+     */
+    public GetJobStatsResponse getJobStats(GetJobStatsRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request,
+                MLRequestConverters::getJobStats,
+                options,
+                GetJobStatsResponse::fromXContent,
+                Collections.emptySet());
+    }
+
+    /**
+     * Gets one or more Machine Learning job configuration info, asynchronously.
+     *
+     * <p>
+     *     For additional info
+     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job-stats.html">Get Job stats docs</a>
+     * </p>
+     * @param request {@link GetJobStatsRequest} Request containing a list of jobId(s) and additional options
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener Listener to be notified with {@link GetJobStatsResponse} upon request completion
+     */
+    public void getJobStatsAsync(GetJobStatsRequest request, RequestOptions options, ActionListener<GetJobStatsResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request,
+                MLRequestConverters::getJobStats,
+                options,
+                GetJobStatsResponse::fromXContent,
+                listener,
+                Collections.emptySet());
+    }
+
     /**
      * Deletes the given Machine Learning Job
      * <p>
@@ -257,42 +300,6 @@ public void closeJobAsync(CloseJobRequest request, RequestOptions options, Actio
             Collections.emptySet());
     }
 
-    /**
-     * Gets the buckets for a Machine Learning Job.
-     * <p>
-     * For additional info
-     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-bucket.html">ML GET buckets documentation</a>
-     *
-     * @param request  The request
-     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
-     */
-    public GetBucketsResponse getBuckets(GetBucketsRequest request, RequestOptions options) throws IOException {
-        return restHighLevelClient.performRequestAndParseEntity(request,
-                MLRequestConverters::getBuckets,
-                options,
-                GetBucketsResponse::fromXContent,
-                Collections.emptySet());
-    }
-
-    /**
-     * Gets the buckets for a Machine Learning Job, notifies listener once the requested buckets are retrieved.
-     * <p>
-     * For additional info
-     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-bucket.html">ML GET buckets documentation</a>
-     *
-     * @param request  The request
-     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
-     * @param listener Listener to be notified upon request completion
-     */
-    public void getBucketsAsync(GetBucketsRequest request, RequestOptions options, ActionListener<GetBucketsResponse> listener) {
-        restHighLevelClient.performRequestAsyncAndParseEntity(request,
-                MLRequestConverters::getBuckets,
-                options,
-                GetBucketsResponse::fromXContent,
-                listener,
-                Collections.emptySet());
-     }
-
     /**
      * Flushes internally buffered data for the given Machine Learning Job ensuring all data sent to the has been processed.
      * This may cause new results to be calculated depending on the contents of the buffer
@@ -311,13 +318,13 @@ public void getBucketsAsync(GetBucketsRequest request, RequestOptions options, A
      * @param request  The {@link FlushJobRequest} object enclosing the `jobId` and additional request options
      * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      */
-     public FlushJobResponse flushJob(FlushJobRequest request, RequestOptions options) throws IOException {
+    public FlushJobResponse flushJob(FlushJobRequest request, RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(request,
-            MLRequestConverters::flushJob,
-            options,
-            FlushJobResponse::fromXContent,
-            Collections.emptySet());
-     }
+                MLRequestConverters::flushJob,
+                options,
+                FlushJobResponse::fromXContent,
+                Collections.emptySet());
+    }
 
     /**
      * Flushes internally buffered data for the given Machine Learning Job asynchronously ensuring all data sent to the has been processed.
@@ -338,54 +345,88 @@ public FlushJobResponse flushJob(FlushJobRequest request, RequestOptions options
      * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @param listener Listener to be notified upon request completion
      */
-     public void flushJobAsync(FlushJobRequest request, RequestOptions options, ActionListener<FlushJobResponse> listener) {
-         restHighLevelClient.performRequestAsyncAndParseEntity(request,
-             MLRequestConverters::flushJob,
-             options,
-             FlushJobResponse::fromXContent,
-             listener,
-             Collections.emptySet());
-     }
+    public void flushJobAsync(FlushJobRequest request, RequestOptions options, ActionListener<FlushJobResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request,
+                MLRequestConverters::flushJob,
+                options,
+                FlushJobResponse::fromXContent,
+                listener,
+                Collections.emptySet());
+    }
 
-     /**
-     * Gets usage statistics for one or more Machine Learning jobs
-     *
+    /**
+     * Gets the buckets for a Machine Learning Job.
      * <p>
-     *     For additional info
-     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job-stats.html">Get Job stats docs</a>
-     * </p>
-     * @param request {@link GetJobStatsRequest} Request containing a list of jobId(s) and additional options
+     * For additional info
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-bucket.html">ML GET buckets documentation</a>
+     *
+     * @param request  The request
      * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
-     * @return {@link GetJobStatsResponse} response object containing
-     * the {@link JobStats} objects and the number of jobs found
-     * @throws IOException when there is a serialization issue sending the request or receiving the response
      */
-    public GetJobStatsResponse getJobStats(GetJobStatsRequest request, RequestOptions options) throws IOException {
+    public GetBucketsResponse getBuckets(GetBucketsRequest request, RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(request,
-            MLRequestConverters::getJobStats,
-            options,
-            GetJobStatsResponse::fromXContent,
-            Collections.emptySet());
+                MLRequestConverters::getBuckets,
+                options,
+                GetBucketsResponse::fromXContent,
+                Collections.emptySet());
     }
 
     /**
-     * Gets one or more Machine Learning job configuration info, asynchronously.
+     * Gets the buckets for a Machine Learning Job, notifies listener once the requested buckets are retrieved.
+     * <p>
+     * For additional info
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-bucket.html">ML GET buckets documentation</a>
+     *
+     * @param request  The request
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener Listener to be notified upon request completion
+     */
+    public void getBucketsAsync(GetBucketsRequest request, RequestOptions options, ActionListener<GetBucketsResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request,
+                MLRequestConverters::getBuckets,
+                options,
+                GetBucketsResponse::fromXContent,
+                listener,
+                Collections.emptySet());
+     }
+
+    /**
+     * Gets overall buckets for a set of Machine Learning Jobs.
+     * <p>
+     * For additional info
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-overall-buckets.html">
+     *     ML GET overall buckets documentation</a>
      *
+     * @param request  The request
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     */
+    public GetOverallBucketsResponse getOverallBuckets(GetOverallBucketsRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request,
+                MLRequestConverters::getOverallBuckets,
+                options,
+                GetOverallBucketsResponse::fromXContent,
+                Collections.emptySet());
+    }
+
+    /**
+     * Gets overall buckets for a set of Machine Learning Jobs, notifies listener once the requested buckets are retrieved.
      * <p>
-     *     For additional info
-     *     see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job-stats.html">Get Job stats docs</a>
-     * </p>
-     * @param request {@link GetJobStatsRequest} Request containing a list of jobId(s) and additional options
+     * For additional info
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-overall-buckets.html">
+     *     ML GET overall buckets documentation</a>
+     *
+     * @param request  The request
      * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
-     * @param listener Listener to be notified with {@link GetJobStatsResponse} upon request completion
+     * @param listener Listener to be notified upon request completion
      */
-    public void getJobStatsAsync(GetJobStatsRequest request, RequestOptions options, ActionListener<GetJobStatsResponse> listener) {
+    public void getOverallBucketsAsync(GetOverallBucketsRequest request, RequestOptions options,
+                                       ActionListener<GetOverallBucketsResponse> listener) {
         restHighLevelClient.performRequestAsyncAndParseEntity(request,
-            MLRequestConverters::getJobStats,
-            options,
-            GetJobStatsResponse::fromXContent,
-            listener,
-            Collections.emptySet());
+                MLRequestConverters::getOverallBuckets,
+                options,
+                GetOverallBucketsResponse::fromXContent,
+                listener,
+                Collections.emptySet());
     }
 
     /**