[Transform] Implement the ability to preview the existing transform

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

@@ -137,11 +137,16 @@ static Request stopTransform(StopTransformRequest stopRequest) {
     }
 
     static Request previewTransform(PreviewTransformRequest previewRequest) throws IOException {
-        String endpoint = new RequestConverters.EndpointBuilder()
-                .addPathPartAsIs("_transform", "_preview")
-                .build();
+        RequestConverters.EndpointBuilder endpointBuilder = new RequestConverters.EndpointBuilder().addPathPartAsIs("_transform");
+        if (previewRequest.getTransformId() != null) {
+            endpointBuilder.addPathPart(previewRequest.getTransformId());
+        }
+        endpointBuilder.addPathPartAsIs("_preview");
+        String endpoint = endpointBuilder.build();
         Request request = new Request(HttpPost.METHOD_NAME, endpoint);
-        request.setEntity(createEntity(previewRequest, REQUEST_BODY_CONTENT_TYPE));
+        if (previewRequest.getTransformId() == null) {
+            request.setEntity(createEntity(previewRequest, REQUEST_BODY_CONTENT_TYPE));
+        }
         return request;
     }
 

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

@@ -21,10 +21,21 @@
 
 public class PreviewTransformRequest implements ToXContentObject, Validatable {
 
+    private final String transformId;
     private final TransformConfig config;
 
+    public PreviewTransformRequest(String transformId) {
+        this.transformId = Objects.requireNonNull(transformId);
+        this.config = null;
+    }
+
     public PreviewTransformRequest(TransformConfig config) {
-        this.config = config;
+        this.transformId = null;
+        this.config = Objects.requireNonNull(config);
+    }
+
+    public String getTransformId() {
+        return transformId;
     }
 
     public TransformConfig getConfig() {
@@ -33,16 +44,20 @@ public TransformConfig getConfig() {
 
     @Override
     public XContentBuilder toXContent(XContentBuilder builder, ToXContent.Params params) throws IOException {
-        return config.toXContent(builder, params);
+        if (this.config != null) {
+            return this.config.toXContent(builder, params);
+        } else {
+            return builder
+                .startObject()
+                .field(TransformConfig.ID.getPreferredName(), this.transformId)
+                .endObject();
+        }
     }
 
     @Override
     public Optional<ValidationException> validate() {
         ValidationException validationException = new ValidationException();
-        if (config == null) {
-            validationException.addValidationError("preview requires a non-null transform config");
-            return Optional.of(validationException);
-        } else {
+        if (config != null) {
             if (config.getSource() == null) {
                 validationException.addValidationError("transform source cannot be null");
             }
@@ -57,7 +72,7 @@ public Optional<ValidationException> validate() {
 
     @Override
     public int hashCode() {
-        return Objects.hash(config);
+        return Objects.hash(transformId, config);
     }
 
     @Override
@@ -69,6 +84,7 @@ public boolean equals(Object obj) {
             return false;
         }
         PreviewTransformRequest other = (PreviewTransformRequest) obj;
-        return Objects.equals(config, other.config);
+        return Objects.equals(transformId, other.transformId)
+            && Objects.equals(config, other.config);
     }
 }

client/rest-high-level/src/test/java/org/elasticsearch/client/TransformIT.java

@@ -336,7 +336,6 @@ public void testStartStop() throws IOException {
         assertThat(taskState, is(TransformStats.State.STOPPED));
     }
 
-    @SuppressWarnings("unchecked")
     public void testPreview() throws IOException {
         String sourceIndex = "transform-source";
         createIndex(sourceIndex);
@@ -345,12 +344,28 @@ public void testPreview() throws IOException {
         TransformConfig transform = validDataFrameTransformConfig("test-preview", sourceIndex, null);
 
         TransformClient client = highLevelClient().transform();
-        PreviewTransformResponse preview = execute(
-            new PreviewTransformRequest(transform),
-            client::previewTransform,
-            client::previewTransformAsync
-        );
+        PreviewTransformResponse preview =
+            execute(new PreviewTransformRequest(transform), client::previewTransform, client::previewTransformAsync);
+        assertExpectedPreview(preview);
+    }
+
+    public void testPreviewById() throws IOException {
+        String sourceIndex = "transform-source";
+        createIndex(sourceIndex);
+        indexData(sourceIndex);
 
+        String transformId = "test-preview-by-id";
+        TransformConfig transform = validDataFrameTransformConfig(transformId, sourceIndex, "pivot-dest");
+        putTransform(transform);
+
+        TransformClient client = highLevelClient().transform();
+        PreviewTransformResponse preview =
+            execute(new PreviewTransformRequest(transformId), client::previewTransform, client::previewTransformAsync);
+        assertExpectedPreview(preview);
+    }
+
+    @SuppressWarnings("unchecked")
+    private static void assertExpectedPreview(PreviewTransformResponse preview) {
         List<Map<String, Object>> docs = preview.getDocs();
         assertThat(docs, hasSize(2));
         Optional<Map<String, Object>> theresa = docs.stream().filter(doc -> "theresa".equals(doc.get("reviewer"))).findFirst();

client/rest-high-level/src/test/java/org/elasticsearch/client/TransformRequestConvertersTests.java

@@ -17,6 +17,7 @@
 import org.elasticsearch.client.transform.GetTransformRequest;
 import org.elasticsearch.client.transform.GetTransformStatsRequest;
 import org.elasticsearch.client.transform.PreviewTransformRequest;
+import org.elasticsearch.client.transform.PreviewTransformRequestTests;
 import org.elasticsearch.client.transform.PutTransformRequest;
 import org.elasticsearch.client.transform.StartTransformRequest;
 import org.elasticsearch.client.transform.StopTransformRequest;
@@ -44,6 +45,7 @@
 import static org.hamcrest.Matchers.hasEntry;
 import static org.hamcrest.Matchers.hasKey;
 import static org.hamcrest.Matchers.not;
+import static org.hamcrest.Matchers.nullValue;
 
 public class TransformRequestConvertersTests extends ESTestCase {
 
@@ -176,19 +178,28 @@ public void testStopDataFrameTransform() {
     }
 
     public void testPreviewDataFrameTransform() throws IOException {
-        PreviewTransformRequest previewRequest = new PreviewTransformRequest(
-                TransformConfigTests.randomTransformConfig());
+        PreviewTransformRequest previewRequest = new PreviewTransformRequest(TransformConfigTests.randomTransformConfig());
         Request request = TransformRequestConverters.previewTransform(previewRequest);
 
         assertEquals(HttpPost.METHOD_NAME, request.getMethod());
         assertThat(request.getEndpoint(), equalTo("/_transform/_preview"));
 
         try (XContentParser parser = createParser(JsonXContent.jsonXContent, request.getEntity().getContent())) {
-            TransformConfig parsedConfig = TransformConfig.PARSER.apply(parser, null);
-            assertThat(parsedConfig, equalTo(previewRequest.getConfig()));
+            PreviewTransformRequest parsedRequest = PreviewTransformRequestTests.fromXContent(parser);
+            assertThat(parsedRequest, equalTo(previewRequest));
         }
     }
 
+    public void testPreviewDataFrameTransformById() throws IOException {
+        String transformId = randomAlphaOfLengthBetween(1, 10);
+        PreviewTransformRequest previewRequest = new PreviewTransformRequest(transformId);
+        Request request = TransformRequestConverters.previewTransform(previewRequest);
+
+        assertEquals(HttpPost.METHOD_NAME, request.getMethod());
+        assertThat(request.getEndpoint(), equalTo("/_transform/" + transformId + "/_preview"));
+        assertThat(request.getEntity(), nullValue());
+    }
+
     public void testGetDataFrameTransformStats() {
         GetTransformStatsRequest getStatsRequest = new GetTransformStatsRequest("foo");
         Request request = TransformRequestConverters.getTransformStats(getStatsRequest);

client/rest-high-level/src/test/java/org/elasticsearch/client/transform/PreviewTransformRequestTests.java

@@ -13,15 +13,21 @@
 import org.elasticsearch.client.transform.transforms.TransformConfigTests;
 import org.elasticsearch.client.transform.transforms.latest.LatestConfigTests;
 import org.elasticsearch.client.transform.transforms.pivot.PivotConfigTests;
+import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.common.xcontent.LoggingDeprecationHandler;
 import org.elasticsearch.common.xcontent.NamedXContentRegistry;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.common.xcontent.XContentFactory;
 import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.common.xcontent.XContentType;
 import org.elasticsearch.search.SearchModule;
 import org.elasticsearch.test.AbstractXContentTestCase;
 
 import java.io.IOException;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 import static org.elasticsearch.client.transform.transforms.SourceConfigTests.randomSourceConfig;
@@ -32,12 +38,35 @@
 public class PreviewTransformRequestTests extends AbstractXContentTestCase<PreviewTransformRequest> {
     @Override
     protected PreviewTransformRequest createTestInstance() {
-        return new PreviewTransformRequest(TransformConfigTests.randomTransformConfig());
+        return randomBoolean()
+            ? new PreviewTransformRequest(randomAlphaOfLengthBetween(1, 10))
+            : new PreviewTransformRequest(TransformConfigTests.randomTransformConfig());
     }
 
     @Override
     protected PreviewTransformRequest doParseInstance(XContentParser parser) throws IOException {
-        return new PreviewTransformRequest(TransformConfig.fromXContent(parser));
+        return fromXContent(parser);
+    }
+
+    public static PreviewTransformRequest fromXContent(XContentParser parser) throws IOException {
+        Map<String, Object> content = parser.map();
+        if (content.size() == 1 && content.containsKey(TransformConfig.ID.getPreferredName())) {
+            // The request only contains transform id so instead of parsing TransformConfig (which is pointless in this case),
+            // let's just fetch the transform config by id later on.
+            String transformId = (String) content.get(TransformConfig.ID.getPreferredName());
+            return new PreviewTransformRequest(transformId);
+        }
+        try (
+            XContentBuilder xContentBuilder = XContentFactory.jsonBuilder().map(content);
+            XContentParser newParser = XContentType.JSON.xContent()
+                .createParser(
+                    parser.getXContentRegistry(),
+                    LoggingDeprecationHandler.INSTANCE,
+                    BytesReference.bytes(xContentBuilder).streamInput()
+                )
+        ) {
+            return new PreviewTransformRequest(TransformConfig.fromXContent(newParser));
+        }
     }
 
     @Override
@@ -54,10 +83,13 @@ protected NamedXContentRegistry xContentRegistry() {
         return new NamedXContentRegistry(namedXContents);
     }
 
+    public void testConstructorThrowsNPE() {
+        expectThrows(NullPointerException.class, () -> new PreviewTransformRequest((String) null));
+        expectThrows(NullPointerException.class, () -> new PreviewTransformRequest((TransformConfig) null));
+    }
+
     public void testValidate() {
         assertThat(new PreviewTransformRequest(TransformConfigTests.randomTransformConfig()).validate(), isEmpty());
-        assertThat(new PreviewTransformRequest(null).validate().get().getMessage(),
-                containsString("preview requires a non-null transform config"));
 
         // null id and destination is valid
         TransformConfig config = TransformConfig.forPreview(randomSourceConfig(), PivotConfigTests.randomPivotConfig());

docs/reference/transform/apis/preview-transform.asciidoc

@@ -13,8 +13,16 @@ Previews a {transform}.
 [[preview-transform-request]]
 == {api-request-title}
 
+
+`GET _transform/<transform_id>/_preview` +
+
+`POST _transform/<transform_id>/_preview` +
+
+`GET _transform/_preview` +
+
 `POST _transform/_preview`
 
+
 [[preview-transform-prereq]]
 == {api-prereq-title}
 
@@ -46,6 +54,17 @@ You must choose either the `latest` or `pivot` method for your {transform}; you
 cannot use both in a single {transform}.
 
 [role="child_attributes"]
+
+[[preview-transform-path-params]]
+== {api-path-parms-title}
+
+`<transform_id>`::
+(Optional, string)
+Id of the {transform} to preview.
++
+NOTE: If you provide the `<transform_id>` as a path parameter, you cannot
+provide {transform} configuration details in the request body.
+
 [[preview-transform-request-body]]
 == {api-request-body-title}
 

rest-api-spec/src/main/resources/rest-api-spec/api/transform.preview_transform.json

@@ -12,17 +12,31 @@
     },
     "url":{
       "paths":[
+        {
+          "path":"/_transform/{transform_id}/_preview",
+          "methods":[
+            "GET",
+            "POST"
+          ],
+          "parts":{
+            "transform_id":{
+              "type":"string",
+              "description":"The id of the transform to preview."
+            }
+          }
+        },
         {
           "path":"/_transform/_preview",
           "methods":[
+            "GET",
             "POST"
           ]
         }
       ]
     },
     "body":{
       "description":"The definition for the transform to preview",
-      "required":true
+      "required":false
     }
   }
 }