[7.x][ML] Explain data frame analytics API (#49455) (#49504)

This commit replaces the _estimate_memory_usage API with
a new API, the _explain API.

The API consolidates information that is useful before
creating a data frame analytics job.

It includes:

- memory estimation
- field selection explanation

Memory estimation is moved here from what was previously
calculated in the _estimate_memory_usage API.

Field selection is a new feature that explains to the user
whether each available field was selected to be included or
not in the analysis. In the case it was not included, it also
explains the reason why.

Backport of #49455

Author: dimitris-athanasiou

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

@@ -29,6 +29,7 @@
 import org.elasticsearch.client.RequestConverters.EndpointBuilder;
 import org.elasticsearch.client.core.PageParams;
 import org.elasticsearch.client.ml.CloseJobRequest;
+import org.elasticsearch.client.ml.ExplainDataFrameAnalyticsRequest;
 import org.elasticsearch.client.ml.DeleteCalendarEventRequest;
 import org.elasticsearch.client.ml.DeleteCalendarJobRequest;
 import org.elasticsearch.client.ml.DeleteCalendarRequest;
@@ -701,12 +702,17 @@ static Request evaluateDataFrame(EvaluateDataFrameRequest evaluateRequest) throw
         return request;
     }
 
-    static Request estimateMemoryUsage(PutDataFrameAnalyticsRequest estimateRequest) throws IOException {
-        String endpoint = new EndpointBuilder()
-            .addPathPartAsIs("_ml", "data_frame", "analytics", "_estimate_memory_usage")
-            .build();
-        Request request = new Request(HttpPost.METHOD_NAME, endpoint);
-        request.setEntity(createEntity(estimateRequest, REQUEST_BODY_CONTENT_TYPE));
+    static Request explainDataFrameAnalytics(ExplainDataFrameAnalyticsRequest explainRequest) throws IOException {
+        EndpointBuilder endpoint = new EndpointBuilder().addPathPartAsIs("_ml", "data_frame", "analytics");
+        if (explainRequest.getId() != null) {
+            endpoint.addPathPart(explainRequest.getId());
+        }
+        endpoint.addPathPartAsIs("_explain");
+
+        Request request = new Request(HttpPost.METHOD_NAME, endpoint.build());
+        if (explainRequest.getConfig() != null) {
+            request.setEntity(createEntity(explainRequest.getConfig(), REQUEST_BODY_CONTENT_TYPE));
+        }
         return request;
     }
 

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

@@ -22,6 +22,8 @@
 import org.elasticsearch.action.support.master.AcknowledgedResponse;
 import org.elasticsearch.client.ml.CloseJobRequest;
 import org.elasticsearch.client.ml.CloseJobResponse;
+import org.elasticsearch.client.ml.ExplainDataFrameAnalyticsRequest;
+import org.elasticsearch.client.ml.ExplainDataFrameAnalyticsResponse;
 import org.elasticsearch.client.ml.DeleteCalendarEventRequest;
 import org.elasticsearch.client.ml.DeleteCalendarJobRequest;
 import org.elasticsearch.client.ml.DeleteCalendarRequest;
@@ -34,7 +36,6 @@
 import org.elasticsearch.client.ml.DeleteJobRequest;
 import org.elasticsearch.client.ml.DeleteJobResponse;
 import org.elasticsearch.client.ml.DeleteModelSnapshotRequest;
-import org.elasticsearch.client.ml.EstimateMemoryUsageResponse;
 import org.elasticsearch.client.ml.EvaluateDataFrameRequest;
 import org.elasticsearch.client.ml.EvaluateDataFrameResponse;
 import org.elasticsearch.client.ml.FindFileStructureRequest;
@@ -2249,46 +2250,46 @@ public Cancellable evaluateDataFrameAsync(EvaluateDataFrameRequest request, Requ
     }
 
     /**
-     * Estimates memory usage for the given Data Frame Analytics
+     * Explains the given Data Frame Analytics
      * <p>
      * For additional info
-     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/estimate-memory-usage-dfanalytics.html">
-     *     Estimate Memory Usage for Data Frame Analytics documentation</a>
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/explain-dfanalytics.html">
+     *     Explain Data Frame Analytics documentation</a>
      *
-     * @param request The {@link PutDataFrameAnalyticsRequest}
+     * @param request The {@link ExplainDataFrameAnalyticsRequest}
      * @param options Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
-     * @return {@link EstimateMemoryUsageResponse} response object
+     * @return {@link ExplainDataFrameAnalyticsResponse} response object
      * @throws IOException when there is a serialization issue sending the request or receiving the response
      */
-    public EstimateMemoryUsageResponse estimateMemoryUsage(PutDataFrameAnalyticsRequest request,
-                                                           RequestOptions options) throws IOException {
+    public ExplainDataFrameAnalyticsResponse explainDataFrameAnalytics(ExplainDataFrameAnalyticsRequest request,
+                                                                       RequestOptions options) throws IOException {
         return restHighLevelClient.performRequestAndParseEntity(
             request,
-            MLRequestConverters::estimateMemoryUsage,
+            MLRequestConverters::explainDataFrameAnalytics,
             options,
-            EstimateMemoryUsageResponse::fromXContent,
+            ExplainDataFrameAnalyticsResponse::fromXContent,
             Collections.emptySet());
     }
 
     /**
-     * Estimates memory usage for the given Data Frame Analytics asynchronously and notifies listener upon completion
+     * Explains the given Data Frame Analytics asynchronously and notifies listener upon completion
      * <p>
      * For additional info
-     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/estimate-memory-usage-dfanalytics.html">
-     *     Estimate Memory Usage for Data Frame Analytics documentation</a>
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/explain-dfanalytics.html">
+     *     Explain Data Frame Analytics documentation</a>
      *
-     * @param request The {@link PutDataFrameAnalyticsRequest}
+     * @param request The {@link ExplainDataFrameAnalyticsRequest}
      * @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
      * @return cancellable that may be used to cancel the request
      */
-    public Cancellable estimateMemoryUsageAsync(PutDataFrameAnalyticsRequest request, RequestOptions options,
-                                                ActionListener<EstimateMemoryUsageResponse> listener) {
+    public Cancellable explainDataFrameAnalyticsAsync(ExplainDataFrameAnalyticsRequest request, RequestOptions options,
+                                                      ActionListener<ExplainDataFrameAnalyticsResponse> listener) {
         return restHighLevelClient.performRequestAsyncAndParseEntity(
             request,
-            MLRequestConverters::estimateMemoryUsage,
+            MLRequestConverters::explainDataFrameAnalytics,
             options,
-            EstimateMemoryUsageResponse::fromXContent,
+            ExplainDataFrameAnalyticsResponse::fromXContent,
             listener,
             Collections.emptySet());
     }

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

@@ -0,0 +1,72 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client.ml;
+
+import org.elasticsearch.client.Validatable;
+import org.elasticsearch.client.ml.dataframe.DataFrameAnalyticsConfig;
+import org.elasticsearch.common.Nullable;
+
+import java.util.Objects;
+
+/**
+ * Request to explain the following about a data frame analytics job:
+ * <ul>
+ *     <li>field selection: which fields are included or are not in the analysis</li>
+ *     <li>memory estimation: how much memory the job is estimated to require</li>
+ * </ul>
+ */
+public class ExplainDataFrameAnalyticsRequest implements Validatable {
+
+    private final String id;
+    private final DataFrameAnalyticsConfig config;
+
+    public ExplainDataFrameAnalyticsRequest(String id) {
+        this.id = Objects.requireNonNull(id);
+        this.config = null;
+    }
+
+    public ExplainDataFrameAnalyticsRequest(DataFrameAnalyticsConfig config) {
+        this.id = null;
+        this.config = Objects.requireNonNull(config);
+    }
+
+    @Nullable
+    public String getId() {
+        return id;
+    }
+
+    @Nullable
+    public DataFrameAnalyticsConfig getConfig() {
+        return config;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+
+        ExplainDataFrameAnalyticsRequest other = (ExplainDataFrameAnalyticsRequest) o;
+        return Objects.equals(id, other.id) && Objects.equals(config, other.config);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id, config);
+    }
+}

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

@@ -0,0 +1,94 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client.ml;
+
+import org.elasticsearch.client.ml.dataframe.explain.FieldSelection;
+import org.elasticsearch.client.ml.dataframe.explain.MemoryEstimation;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.ToXContentObject;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.common.xcontent.XContentParser;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Objects;
+
+public class ExplainDataFrameAnalyticsResponse implements ToXContentObject {
+
+    public static final ParseField TYPE = new ParseField("explain_data_frame_analytics_response");
+
+    public static final ParseField FIELD_SELECTION = new ParseField("field_selection");
+    public static final ParseField MEMORY_ESTIMATION = new ParseField("memory_estimation");
+
+    public static ExplainDataFrameAnalyticsResponse fromXContent(XContentParser parser) throws IOException {
+        return PARSER.parse(parser, null);
+    }
+
+    @SuppressWarnings("unchecked")
+    static final ConstructingObjectParser<ExplainDataFrameAnalyticsResponse, Void> PARSER =
+        new ConstructingObjectParser<>(
+            TYPE.getPreferredName(), true,
+            args -> new ExplainDataFrameAnalyticsResponse((List<FieldSelection>) args[0], (MemoryEstimation) args[1]));
+
+    static {
+        PARSER.declareObjectArray(ConstructingObjectParser.constructorArg(), FieldSelection.PARSER, FIELD_SELECTION);
+        PARSER.declareObject(ConstructingObjectParser.constructorArg(), MemoryEstimation.PARSER, MEMORY_ESTIMATION);
+    }
+
+    private final List<FieldSelection> fieldSelection;
+    private final MemoryEstimation memoryEstimation;
+
+    public ExplainDataFrameAnalyticsResponse(List<FieldSelection> fieldSelection, MemoryEstimation memoryEstimation) {
+        this.fieldSelection = Objects.requireNonNull(fieldSelection);
+        this.memoryEstimation = Objects.requireNonNull(memoryEstimation);
+    }
+
+    @Override
+    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
+        builder.startObject();
+        builder.field(FIELD_SELECTION.getPreferredName(), fieldSelection);
+        builder.field(MEMORY_ESTIMATION.getPreferredName(), memoryEstimation);
+        builder.endObject();
+        return builder;
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        if (this == other) return true;
+        if (other == null || getClass() != other.getClass()) return false;
+
+        ExplainDataFrameAnalyticsResponse that = (ExplainDataFrameAnalyticsResponse) other;
+        return Objects.equals(fieldSelection, that.fieldSelection)
+            && Objects.equals(memoryEstimation, that.memoryEstimation);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(fieldSelection, memoryEstimation);
+    }
+
+    public MemoryEstimation getMemoryEstimation() {
+        return memoryEstimation;
+    }
+
+    public List<FieldSelection> getFieldSelection() {
+        return fieldSelection;
+    }
+}