Added specs and tests for /_plugins/_transform. (#722)

dblock · nhtruong · web-flow · commit 6341e87326b2 · 2024-12-10T12:40:18.000-07:00
Signed-off-by: dblock &lt;dblock@amazon.com&gt;
Signed-off-by: Theo N. Truong &lt;theotr@amazon.com&gt;
Co-authored-by: Theo N. Truong &lt;theotr@amazon.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added schema for `/_plugins/_knn/stats`, `/_plugins/_knn/models/{model_id}`, `_train` and `_search` ([#704](https://github.com/opensearch-project/opensearch-api-specification/pull/704))
 - Added `retry` support in `prologues` and `epilogues` ([#713](https://github.com/opensearch-project/opensearch-api-specification/pull/713))
 - Added response schema for `DELETE /_plugins/_rollup/jobs/{id}`, `POST /_plugins/_rollup/jobs/{id}/_start` and `_stop` ([#716](https://github.com/opensearch-project/opensearch-api-specification/pull/716))
+- Added response schema for `PUT` and `DELETE /_plugins/_transform/{id}` ([#722](https://github.com/opensearch-project/opensearch-api-specification/pull/716))
 - Added response schema for `GET /_plugins/_knn/warmup/{index}` ([#717](https://github.com/opensearch-project/opensearch-api-specification/pull/717))
 
 ### Removed
diff --git a/spec/namespaces/transforms.yaml b/spec/namespaces/transforms.yaml
@@ -48,6 +48,8 @@ paths:
       requestBody:
         $ref: '#/components/requestBodies/transforms.put'
       responses:
+        '201':
+          $ref: '#/components/responses/transforms.put@201'
         '200':
           $ref: '#/components/responses/transforms.put@200'
     delete:
@@ -120,17 +122,12 @@ components:
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              transform:
-                $ref: '../schemas/transforms._common.yaml#/components/schemas/Transform'
-            required:
-              - transform
+            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformRequest'
     transforms.put:
       content:
         application/json:
           schema:
-            $ref: '../schemas/transforms._common.yaml#/components/schemas/Transform'
+            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformRequest'
   responses:
     transforms.search@200:
       content:
@@ -141,13 +138,22 @@ components:
       content:
         application/json:
           schema:
-            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformEntity'
+            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformResponse'
     transforms.put@200:
       content:
         application/json:
           schema:
-            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformEntity'
-    transforms.delete@200: {}
+            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformResponse'
+    transforms.put@201:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/transforms._common.yaml#/components/schemas/TransformResponse'
+    transforms.delete@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/transforms._common.yaml#/components/schemas/DeleteTransformsResponse'
     transforms.start@200:
       content:
         application/json:
diff --git a/spec/schemas/transforms._common.yaml b/spec/schemas/transforms._common.yaml
@@ -5,15 +5,25 @@ info:
   version: 1.0.0
 components:
   schemas:
-    TransformEntity:
+    TransformRequest:
+      type: object
+      properties:
+        transform:
+          $ref: '#/components/schemas/Transform'
+      required:
+        - transform
+    TransformResponse:
       type: object
       properties:
         _id:
-          type: string
-        _seqNo:
-          type: number
-        _primaryTerm:
-          type: number
+          $ref: '_common.yaml#/components/schemas/Id'
+        _primary_term:
+          type: integer
+          format: int64
+        _seq_no:
+          $ref: '_common.yaml#/components/schemas/SequenceNumber'
+        _version:
+          $ref: '_common.yaml#/components/schemas/VersionNumber'
         transform:
           $ref: '#/components/schemas/Transform'
     TransformsResponse:
@@ -24,7 +34,58 @@ components:
         transforms:
           type: array
           items:
-            $ref: '#/components/schemas/TransformEntity'
+            $ref: '#/components/schemas/TransformResponse'
+    DeleteTransformsResponse:
+      type: object
+      properties:
+        took:
+          type: integer
+          format: int64
+        errors:
+          type: boolean
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/DeleteTransformResponseItem'
+    DeleteTransformResponseItem:
+      type: object
+      properties:
+        delete:
+          $ref: '#/components/schemas/DeletedTransformResponse'      
+    DeletedTransformResponse:
+      type: object
+      properties:
+        _type:
+          $ref: '_common.yaml#/components/schemas/Type'
+        _index:
+          type: string
+        _id:
+          $ref: '_common.yaml#/components/schemas/Id'
+        _version:
+          $ref: '_common.yaml#/components/schemas/VersionNumber'
+        result:
+          type: string
+        forced_refresh:
+          type: boolean
+        _shards:
+          $ref: '_common.yaml#/components/schemas/ShardStatistics'
+        _primary_term:
+          type: integer
+          format: int64
+        _seq_no:
+          $ref: '_common.yaml#/components/schemas/SequenceNumber'
+        status:
+          type: number
+      required:
+        - _id
+        - _index
+        - _primary_term
+        - _seq_no
+        - _shards
+        - _version
+        - forced_refresh
+        - result
+        - status
     Transform:
       type: object
       properties:
@@ -37,13 +98,13 @@ components:
         schedule:
           $ref: '#/components/schemas/Schedule'
         metadata_id:
-          type: string
+          type: ['null', string]
         updated_at:
-          type: string
+          type: number
         enabled:
           type: boolean
         enabled_at:
-          type: number
+          type: ['null', number]
         description:
           type: string
         source_index:
@@ -63,9 +124,9 @@ components:
           items:
             $ref: '#/components/schemas/GroupsConfigItem'
         aggregations: 
-          type: array
-          items:
-            $ref: '#/components/schemas/MetricsConfigItem'
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/GroupsConfigItem'
     ExplainResponse:
       type: object
       additionalProperties:
@@ -74,9 +135,11 @@ components:
       type: object
       properties:
         metadata_id:
-          type: string
+          type: ['null', string]
         transform_metadata:
-          $ref: '#/components/schemas/TransformMetadata'
+          oneOf:
+            - $ref: '#/components/schemas/TransformMetadata'
+            - type: 'null'
     Preview:
       type: object
       properties:
@@ -140,32 +203,6 @@ components:
           type: string
         target_field:
           type: string
-    MetricsConfigItem:
-      type: object
-      properties:
-        source_field:
-          type: string
-        target_field:
-          type: string
-        metrics:
-          type: array
-          items:
-            $ref: '#/components/schemas/MetricsConfigMetrics'
-    MetricsConfigMetrics:
-      type: object
-      properties:
-        avg:
-          type: object
-        sum:
-          type: object
-        max:
-          type: object
-        min:
-          type: object
-        value_count:
-          type: object
-      minProperties: 1
-      maxProperties: 1
     ContinuousStats:
       type: object
       properties:
diff --git a/tests/default/transforms/transform.yaml b/tests/default/transforms/transform.yaml
@@ -0,0 +1,93 @@
+$schema: ../../../json_schemas/test_story.schema.yaml
+
+description: Test transform jobs.
+prologues:
+  - path: /{index}/_doc
+    method: POST
+    parameters:
+      index: movies
+      refresh: true
+    request:
+      payload:
+        title: Beauty and the Beast
+        year: 91
+    status: [201]
+epilogues:
+  - path: /_plugins/_transform/movies-to-films
+    method: DELETE
+    status: [200, 404]
+  - path: /movies
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Create a transform job.
+    id: transform
+    path: /_plugins/_transform/{id}
+    method: PUT
+    parameters:
+      id: movies-to-films
+    request:
+      payload:
+        transform:
+          enabled: false
+          description: A transform.
+          source_index: movies
+          target_index: films
+          data_selection_query:
+            match_all: {}
+          page_size: 10
+          groups:
+            - terms:
+                source_field: year
+                target_field: produced
+          schedule:
+            interval:
+              period: 1
+              unit: Minutes
+              start_time: 1602100553
+    response:
+      status: 201
+    output:
+      primary_term: payload._primary_term
+      seq_no: payload._seq_no
+  - synopsis: Update a transform job.
+    path: /_plugins/_transform/{id}
+    method: PUT
+    parameters:
+      id: movies-to-films
+      if_primary_term: ${transform.primary_term}
+      if_seq_no: ${transform.seq_no}
+    request:
+      payload:
+        transform:
+          enabled: false
+          description: A transform.
+          source_index: movies
+          target_index: films
+          data_selection_query:
+            match_all: {}
+          page_size: 10
+          groups:
+            - terms:
+                source_field: year
+                target_field: produced
+          schedule:
+            interval:
+              period: 1
+              unit: Minutes
+              start_time: 1602100553
+    response:
+      status: 200
+  - synopsis: Get transform jobs.
+    path: /_plugins/_transform
+    method: GET
+  - synopsis: Get a transform job.
+    path: /_plugins/_transform/{id}
+    method: GET
+    parameters:
+      id: movies-to-films
+  - synopsis: Delete a transform job.
+    path: /_plugins/_transform/{id}
+    method: DELETE
+    parameters:
+      id: movies-to-films
diff --git a/tests/default/transforms/transform/explain.yaml b/tests/default/transforms/transform/explain.yaml
@@ -0,0 +1,51 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test explaining a transform job.
+prologues:
+  - path: /{index}/_doc
+    method: POST
+    parameters:
+      index: movies
+      refresh: true
+    request:
+      payload:
+        title: Beauty and the Beast
+        year: 91
+    status: [201]
+  - path: /_plugins/_transform/movies-to-films
+    method: PUT
+    request:
+      payload:
+        transform:
+          enabled: false
+          description: A transform.
+          source_index: movies
+          target_index: films
+          data_selection_query:
+            match_all: {}
+          page_size: 10
+          groups:
+            - terms:
+                source_field: year
+                target_field: produced
+          schedule:
+            interval:
+              period: 1
+              unit: Minutes
+              start_time: 1602100553
+    status: [201]
+epilogues:
+  - path: /_plugins/_transform/movies-to-films
+    parameters:
+      force: true
+    method: DELETE
+    status: [200, 404]
+  - path: /movies
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Explain a transform job.
+    path: /_plugins/_transform/{id}/_explain
+    method: GET
+    parameters:
+      id: movies-to-films
diff --git a/tests/default/transforms/transform/start.yaml b/tests/default/transforms/transform/start.yaml
diff --git a/tests/default/transforms/transform/stop.yaml b/tests/default/transforms/transform/stop.yaml
