adding ppl namespace api specs

CHANGELOG.md

@@ -58,6 +58,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added passing OPENSEARCH_JAVA_OPTS into the docker container used for tests ([#454](https://github.com/opensearch-project/opensearch-api-specification/pull/454))
 - Added a warning on mulitple paths being tested in the same file ([#452](https://github.com/opensearch-project/opensearch-api-specification/pull/452))
 - Added `/_plugins/_query/settings` ([#456](https://github.com/opensearch-project/opensearch-api-specification/pull/456))
+- Added `/_plugins/_ppl`, `explain` and `stats` ([#460](https://github.com/opensearch-project/opensearch-api-specification/pull/460))
 
 ### Changed
 

spec/namespaces/ppl.yaml

@@ -0,0 +1,165 @@
+openapi: 3.1.0
+info:
+  title: OpenSearch PPL API
+  description: OpenSearch PPL API
+  version: 1.0.0
+paths:
+  /_plugins/_ppl:
+    post:
+      operationId: ppl.query.0
+      x-operation-group: ppl.query
+      x-version-added: '1.0'
+      description: Send a PPL query to the PPL plugin. 
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/
+      parameters:
+        - $ref: '#/components/parameters/ppl.query::query.format'
+        - $ref: '#/components/parameters/ppl.query::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/ppl.query'
+      responses:
+        '200':
+          $ref: '#/components/responses/ppl.query@200'
+  /_plugins/_ppl/_explain:
+    post:
+      operationId: ppl.explain.0
+      x-operation-group: ppl.explain
+      x-version-added: '1.0'
+      description: Shows how a query is executed against OpenSearch.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/
+      parameters:
+        - $ref: '#/components/parameters/ppl.explain::query.format'
+        - $ref: '#/components/parameters/ppl.explain::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/ppl.explain'
+      responses:
+        '200':
+          $ref: '#/components/responses/ppl.explain@200'
+  /_plugins/_ppl/stats:
+    get:
+      operationId: ppl.get_stats.0
+      x-operation-group: ppl.get_stats
+      x-version-added: '1.0'
+      description: Collect metrics for the plugin within the interval.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/monitoring/
+      parameters:
+        - $ref: '#/components/parameters/ppl.get_stats::query.format'
+        - $ref: '#/components/parameters/ppl.get_stats::query.sanitize'
+      responses:
+        '200':
+          $ref: '#/components/responses/ppl.get_stats@200'
+    post:
+      operationId: ppl.post_stats.1
+      x-operation-group: ppl.post_stats
+      x-version-added: '1.0'
+      description: By a stats endpoint, you are able to collect metrics for the plugin within the interval.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/monitoring/
+      parameters:
+        - $ref: '#/components/parameters/ppl.post_stats::query.format'
+        - $ref: '#/components/parameters/ppl.post_stats::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/ppl.post_stats'
+      responses:
+        '200':
+          $ref: '#/components/responses/ppl.post_stats@200'
+components:
+  parameters:
+    ppl.query::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+    ppl.query::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results.
+      schema:
+        type: boolean
+        default: true
+    ppl.explain::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+    ppl.explain::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results.
+      schema:
+        type: boolean
+        default: true
+    ppl.get_stats::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+    ppl.get_stats::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results.
+      schema:
+        type: boolean
+        default: true
+    ppl.post_stats::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+    ppl.post_stats::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results.
+      schema:
+        type: boolean
+        default: true
+  requestBodies:
+    ppl.query:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/Query'
+      required: true
+    ppl.explain:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/Explain'
+      required: true
+    ppl.post_stats:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/Stats'
+      required: true
+  responses:
+    ppl.query@200:
+      description: ''
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/QueryResponse'
+    ppl.explain@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/ExplainResponse'
+      required: true
+    ppl.get_stats@200:
+      content:
+        text/plain:
+          schema:
+            type: string
+      required: true
+    ppl.post_stats@200:
+      content:
+        text/plain:
+          schema:
+            type: string
+      required: true

spec/namespaces/sql.yaml

@@ -182,13 +182,13 @@ components:
       content:
         application/json:
           schema:
-            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlQuery'
+            $ref: '../schemas/sql._common.yaml#/components/schemas/Query'
       required: true
     sql.explain:
       content:
         application/json:
           schema:
-            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlExplain'
+            $ref: '../schemas/sql._common.yaml#/components/schemas/Explain'
       required: true
     sql.close:
       content:
@@ -200,7 +200,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlStats'
+            $ref: '../schemas/sql._common.yaml#/components/schemas/Stats'
       required: true
   responses:
     sql.settings@200:
@@ -212,12 +212,12 @@ components:
       content:
         application/json:
           schema:
-            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlQueryResponse'
+            $ref: '../schemas/sql._common.yaml#/components/schemas/QueryResponse'
     sql.explain@200:
       content:
         application/json:
           schema:
-            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlExplainResponse'
+            $ref: '../schemas/sql._common.yaml#/components/schemas/ExplainResponse'
       required: true
     sql.close@200:
       content:

spec/schemas/sql._common.yaml

@@ -6,7 +6,7 @@ info:
 paths: {}
 components:
   schemas:
-    SqlQuery:
+    Query:
       type: object
       properties:
         query:
@@ -15,7 +15,7 @@ components:
           type: object
         fetch_size:
           type: integer
-    SqlQueryResponse:
+    QueryResponse:
       type: object
       properties:
         schema:
@@ -34,7 +34,7 @@ components:
           type: integer
         status:
           type: integer
-    SqlExplain:
+    Explain:
       type: object
       properties:
         query:
@@ -43,12 +43,12 @@ components:
           type: object
         fetch_size:
           type: integer
-    SqlExplainResponse:
+    ExplainResponse:
       type: object
       properties:
         root:
-          $ref: '#/components/schemas/Explain'
-    Explain:
+          $ref: '#/components/schemas/ExplainBody'
+    ExplainBody:
       type: object
       properties:
         name:
@@ -58,18 +58,8 @@ components:
         children:
           type: array
           items: 
-            $ref: '#/components/schemas/Explain'
-    SqlClose:
-      type: object
-      properties:
-        cursor:
-          type: string
-    SqlCloseResponse:
-      type: object
-      properties:
-        succeeded:
-          type: boolean
-    SqlStats:
+            $ref: '#/components/schemas/ExplainBody'
+    Stats:
       type: object
       properties:
         start_time:
@@ -86,6 +76,16 @@ components:
           type: object
         execution_time:
           type: object
+    SqlClose:
+      type: object
+      properties:
+        cursor:
+          type: string
+    SqlCloseResponse:
+      type: object
+      properties:
+        succeeded:
+          type: boolean
     SqlSettings:
       type: object
       properties:
@@ -116,7 +116,7 @@ components:
         ppl:
           $ref: '#/components/schemas/Ppl'
         query:
-          $ref: '#/components/schemas/Query'
+          $ref: '#/components/schemas/PluginsQuery'
         sql:
           $ref: '#/components/schemas/Sql'
     Ppl:
@@ -126,7 +126,7 @@ components:
           anyOf:
             - type: boolean
             - type: string
-    Query:
+    PluginsQuery:
       type: object
       properties:
         memory_limit:
@@ -167,4 +167,4 @@ components:
         plugins.query.memory_limit:
           type: string
         plugins.query.size_limit:
-          type: integer
+          type: integer

tests/ppl/explain.yaml

@@ -0,0 +1,22 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test how a query is executed against OpenSearch.
+
+prologues:
+  - path: /books
+    method: PUT
+    request_body:
+      payload: {}
+epilogues:
+  - path: /books
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Get explain of SQL Query
+    path: /_plugins/_ppl/_explain
+    method: POST
+    request_body:
+      payload:
+        query: search source=books
+    response:
+      status: 200

tests/ppl/query.yaml

@@ -0,0 +1,24 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test send PPL query to index.
+
+prologues:
+  - path: /{index}
+    method: PUT
+    parameters:
+      index: books
+    request_body:
+      payload: {}
+epilogues:
+  - path: /books
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Get PPL query
+    path: /_plugins/_ppl
+    method: POST
+    request_body:
+      payload:
+        query: search source=books
+    response:
+      status: 200

tests/ppl/stats.yaml

@@ -0,0 +1,11 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test get SQL Queries stats.
+
+chapters:
+  - synopsis: Get stats from PPL Query.
+    path: /_plugins/_ppl/stats
+    method: POST
+    response:
+      status: 200
+      content_type: text/plain