diff --git a/.cspell b/.cspell index 37a004c6..08aa8908 100644 --- a/.cspell +++ b/.cspell @@ -177,3 +177,7 @@ urldecode vectory whoamiprotected wordnet +datarows +syserr +cuserr +Rudnick \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index aa24870b..d6563e39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Added AjvErrorsParser to print more informative error messages ([#364](https://github.com/opensearch-project/opensearch-api-specification/issues/364)) - Added JsonSchemaValidator, a wrapper for AJV ([#364](https://github.com/opensearch-project/opensearch-api-specification/issues/364)) - Added support for `application/cbor` responses ([#371](https://github.com/opensearch-project/opensearch-api-specification/pull/371)) +- Added `/_plugins/_sql`, `close`, `explain` and `stats` ([#379](https://github.com/opensearch-project/opensearch-api-specification/pull/379)) +- Added tests for SQL namespace ([#379](https://github.com/opensearch-project/opensearch-api-specification/pull/379)) - Added support for `application/smile` responses ([#386](https://github.com/opensearch-project/opensearch-api-specification/pull/386)) - Added `doc_status`, `remote_store`, `segment_replication` and `unreferenced_file_cleanups_performed` to `SegmentStats` ([#395](https://github.com/opensearch-project/opensearch-api-specification/pull/395)) - Added `concurrent_query_*` and `search_idle_reactivate_count_total` fields to `SearchStats` ([#395](https://github.com/opensearch-project/opensearch-api-specification/pull/395)) diff --git a/spec/namespaces/sql.yaml b/spec/namespaces/sql.yaml new file mode 100644 index 00000000..0afdde2d --- /dev/null +++ b/spec/namespaces/sql.yaml @@ -0,0 +1,216 @@ +openapi: 3.1.0 +info: + title: OpenSearch SQL API + description: OpenSearch SQL API + version: 1.0.0 +paths: + /_plugins/_sql: + post: + operationId: sql.query.0 + x-operation-group: sql.query + x-version-added: '1.0' + description: Send a SQL/PPL query to the SQL plugin. + externalDocs: + url: https://opensearch.org/docs/latest/search-plugins/sql/sql-ppl-api/ + parameters: + - $ref: '#/components/parameters/sql.query::query.format' + - $ref: '#/components/parameters/sql.query::query.sanitize' + requestBody: + $ref: '#/components/requestBodies/sql.query' + 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: 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.get_stats.0 + x-operation-group: sql.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/sql.get_stats::query.format' + - $ref: '#/components/parameters/sql.get_stats::query.sanitize' + responses: + '200': + $ref: '#/components/responses/sql.get_stats@200' + post: + operationId: sql.post_stats.1 + x-operation-group: sql.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/sql.post_stats::query.format' + - $ref: '#/components/parameters/sql.post_stats::query.sanitize' + requestBody: + $ref: '#/components/requestBodies/sql.post_stats' + responses: + '200': + $ref: '#/components/responses/sql.post_stats@200' +components: + parameters: + sql.query::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.query::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.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.get_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.get_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 + sql.post_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.post_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.post_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/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.get_stats@200: + content: + text/plain: + schema: + type: string + required: true + sql.post_stats@200: + content: + text/plain: + schema: + type: string + required: true \ No newline at end of file diff --git a/spec/schemas/sql._common.yaml b/spec/schemas/sql._common.yaml new file mode 100644 index 00000000..ea1abf9f --- /dev/null +++ b/spec/schemas/sql._common.yaml @@ -0,0 +1,88 @@ +openapi: 3.1.0 +info: + title: Schemas of sql._common category. + description: Schemas of sql._common category. + version: 1.0.0 +paths: {} +components: + schemas: + SqlQuery: + type: object + properties: + query: + type: string + filter: + type: object + fetch_size: + type: integer + SqlQueryResponse: + type: object + properties: + schema: + type: array + items: + type: object + datarows: + type: array + items: + type: array + cursor: + type: string + total: + type: integer + size: + type: integer + status: + type: integer + 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: array + 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 \ No newline at end of file diff --git a/tests/sql/close.yaml b/tests/sql/close.yaml new file mode 100644 index 00000000..3c23a629 --- /dev/null +++ b/tests/sql/close.yaml @@ -0,0 +1,49 @@ +$schema: ../../json_schemas/test_story.schema.yaml + +description: Test to explicitly clear the cursor context + +prologues: + - path: /{index} + method: PUT + parameters: + index: books + request_body: + payload: {} + - path: /_bulk + method: POST + request_body: + content_type: application/x-ndjson + payload: + - {create: {_index: books, _id: book_1392214}} + - {author: Harper Lee, title: To Kill a Mockingbird, year: 1960} + - {create: {_index: books, _id: book_1392215}} + - {author: Elizabeth Rudnick, title: Beauty and the Beast, year: 1991} + - path: /{index}/_refresh + method: POST + parameters: + index: books +epilogues: + - path: /books + method: DELETE + status: [200, 404] +chapters: + - synopsis: Get SQL query. + id: query_sql + path: /_plugins/_sql + method: POST + request_body: + payload: + fetch_size: 1 + query: 'SELECT * FROM books' + response: + status: 200 + output: + cursor: payload.cursor + - synopsis: Close cursor. + path: /_plugins/_sql/close + method: POST + request_body: + payload: + cursor: ${query_sql.cursor} + response: + status: 200 \ No newline at end of file diff --git a/tests/sql/explain.yaml b/tests/sql/explain.yaml new file mode 100644 index 00000000..16ea254f --- /dev/null +++ b/tests/sql/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/_sql/_explain + method: POST + request_body: + payload: + query: SELECT * FROM books + response: + status: 200 diff --git a/tests/sql/query.yaml b/tests/sql/query.yaml new file mode 100644 index 00000000..9dba2059 --- /dev/null +++ b/tests/sql/query.yaml @@ -0,0 +1,24 @@ +$schema: ../../json_schemas/test_story.schema.yaml + +description: Test send SQL 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 SQL query + path: /_plugins/_sql + method: POST + request_body: + payload: + query: 'SELECT * FROM books' + response: + status: 200 \ No newline at end of file diff --git a/tests/sql/stats.yaml b/tests/sql/stats.yaml new file mode 100644 index 00000000..cbb8d7db --- /dev/null +++ b/tests/sql/stats.yaml @@ -0,0 +1,11 @@ +$schema: ../../json_schemas/test_story.schema.yaml + +description: Test get SQL Queries stats. + +chapters: + - synopsis: Get stats from SQL Query. + path: /_plugins/_sql/stats + method: POST + response: + status: 200 + content_type: text/plain \ No newline at end of file