added explain, close and stats API specs

Signed-off-by: Tokesh <[email protected]>
opensearch-project · Jul 8, 2024 · 66c2212 · 66c2212
1 parent f24b53d
commit 66c2212
Show file tree

Hide file tree

Showing 2 changed files with 209 additions and 6 deletions.
diff --git a/spec/namespaces/sql.yaml b/spec/namespaces/sql.yaml
@@ -20,6 +20,67 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/sql.query@200'
+  /_plugins/_sql/_explain:
+    post:
+      operationId: sql.explain.0
+      x-operation-group: sql.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/sql.explain::query.format'
+        - $ref: '#/components/parameters/sql.explain::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.explain'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.explain@200'
+  /_plugins/_sql/close:
+    post:
+      operationId: sql.close.0
+      x-operation-group: sql.close
+      x-version-added: '1.0'
+      description: To explicitly clear the cursor context
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/
+      parameters:
+        - $ref: '#/components/parameters/sql.close::query.format'
+        - $ref: '#/components/parameters/sql.close::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.close'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.close@200'
+  /_plugins/_sql/stats:
+    get:
+      operationId: sql.stats.0
+      x-operation-group: sql.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/sql.stats::query.format'
+        - $ref: '#/components/parameters/sql.stats::query.sanitize'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.stats@200'
+    post:
+      operationId: sql.query.0
+      x-operation-group: sql.query
+      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/sql.stats::query.format'
+        - $ref: '#/components/parameters/sql.stats::query.sanitize'
+      requestBody:
+        $ref: '#/components/requestBodies/sql.stats'
+      responses:
+        '200':
+          $ref: '#/components/responses/sql.stats@200'
 components:
   parameters:
     sql.query::query.format:
@@ -36,18 +97,99 @@ components:
       schema:
         type: boolean
         default: true
+        description: Specifies whether to escape special characters in the results
+    sql.explain::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.explain::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+    sql.close::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
+        description: A short version of the Accept header, e.g. json, yaml.
+    sql.close::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
+    sql.stats::query.format:
+      name: format
+      in: query
+      description: A short version of the Accept header, e.g. json, yaml.
+      schema:
+        type: string
         description: A short version of the Accept header, e.g. json, yaml.
+    sql.stats::query.sanitize:
+      name: sanitize
+      in: query
+      description: Specifies whether to escape special characters in the results
+      schema:
+        type: boolean
+        default: true
+        description: Specifies whether to escape special characters in the results
   requestBodies:
     sql.query:
       content:
         application/json:
           schema:
             $ref: '../schemas/sql._common.yaml#/components/schemas/SqlQuery'
       required: true
+    sql.explain:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlExplain'
+      required: true
+    sql.close:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlClose'
+      required: true
+    sql.stats:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlStats'
+      required: true
   responses:
     sql.query@200:
       description: ''
       content:
         application/json:
           schema:
-            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlResponse'
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlQueryResponse'
+    sql.explain@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlExplainResponse'
+      required: true
+    sql.close@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlCloseResponse'
+      required: true
+    sql.stats@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/sql._common.yaml#/components/schemas/SqlStatsResponse'
+      required: true
diff --git a/spec/schemas/sql._common.yaml b/spec/schemas/sql._common.yaml
@@ -15,7 +15,7 @@ components:
           type: object
         fetch_size:
           type: integer
-    SqlResponse:
+    SqlQueryResponse:
       type: object
       properties:
         schema:
@@ -34,7 +34,68 @@ components:
           type: integer
         status:
           type: string
-    # DataRows:
-    #   type: array
-    #   items: object
-
+    SqlExplain:
+      type: object
+      properties:
+        query:
+          type: string
+        filter:
+          type: object
+        fetch_size:
+          type: integer
+    SqlExplainResponse:
+      type: object
+      properties:
+        root:
+          $ref: '#/components/schemas/Explain'
+    Explain:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: object
+        children:
+          type: items
+          items: 
+            $ref: '#/components/schemas/Explain'
+    SqlClose:
+      type: object
+      properties:
+        cursor:
+          type: string
+    SqlCloseResponse:
+      type: object
+      properties:
+        succeeded:
+          type: boolean
+    SqlStats:
+      type: object
+      properties:
+        start_time:
+          type: string
+        end_time:
+          type: object
+        cluster_name:
+          type: object
+        index:
+          type: object
+        query:
+          type: object
+        user:
+          type: object
+        execution_time:
+          type: object
+    SqlStatsResponse:
+      type: object
+      properties:
+        request_total:
+          type: integer
+        request_count:
+          type: integer
+        failed_request_count_syserr:
+          type: integer
+        failed_request_count_cuserr:
+          type: integer
+        failed_request_count_cb:
+          type: integer