From 8bf497c9aa62800b2072bf08d05e9968a62ef858 Mon Sep 17 00:00:00 2001 From: Niyazbek Torekeldi <78027392+Tokesh@users.noreply.github.com> Date: Sat, 3 Aug 2024 19:17:06 +0500 Subject: [PATCH] adding ppl namespace api specs (#460) * adding ppl namespace api specs Signed-off-by: Tokesh * fix lint and adding changelog Signed-off-by: Tokesh * reusing already defined structures Signed-off-by: Tokesh * edit of test descriptions Signed-off-by: Tokesh * fixing descriptions, file structure and deleting semicolons from requestbody Signed-off-by: Tokesh --------- Signed-off-by: Tokesh Signed-off-by: Niyazbek Torekeldi <78027392+Tokesh@users.noreply.github.com> --- CHANGELOG.md | 1 + spec/namespaces/ppl.yaml | 165 ++++++++++++++++++++++++++++++++++ spec/namespaces/sql.yaml | 10 +-- spec/schemas/sql._common.yaml | 42 ++++----- tests/ppl/explain.yaml | 22 +++++ tests/ppl/query.yaml | 24 +++++ tests/ppl/stats.yaml | 11 +++ 7 files changed, 249 insertions(+), 26 deletions(-) create mode 100644 spec/namespaces/ppl.yaml create mode 100644 tests/ppl/explain.yaml create mode 100644 tests/ppl/query.yaml create mode 100644 tests/ppl/stats.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 9385dbda2..e24e482b8 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/spec/namespaces/ppl.yaml b/spec/namespaces/ppl.yaml new file mode 100644 index 000000000..7515cea94 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/spec/namespaces/sql.yaml b/spec/namespaces/sql.yaml index aeba15e55..7de1b1c22 100644 --- a/spec/namespaces/sql.yaml +++ b/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: diff --git a/spec/schemas/sql._common.yaml b/spec/schemas/sql._common.yaml index 3d1a9600d..d9f50ade1 100644 --- a/spec/schemas/sql._common.yaml +++ b/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 \ No newline at end of file + type: integer diff --git a/tests/ppl/explain.yaml b/tests/ppl/explain.yaml new file mode 100644 index 000000000..0dbc465ea --- /dev/null +++ b/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 diff --git a/tests/ppl/query.yaml b/tests/ppl/query.yaml new file mode 100644 index 000000000..53a9720d3 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/ppl/stats.yaml b/tests/ppl/stats.yaml new file mode 100644 index 000000000..ec2786432 --- /dev/null +++ b/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 \ No newline at end of file