From 747f8121603712c2f971e29e410635d52531e168 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Laurent=20Saint-F=C3=A9lix?= Date: Tue, 28 Nov 2023 15:05:10 +0100 Subject: [PATCH] Initial version of ES|QL query endpoint (#2354) * initial version of ESQL query endpoint * Add esql as an import shortcut * Alphabetically reorder body properties * Update specification/esql/query/QueryRequest.ts uppercase CSV Co-authored-by: Bogdan Pintea * Capitalize acronyms * Remove time_zone for the initial version * Fix naming within the documentation string * Add relevant doc_id links to request and params * Explicitely allow multiple types in the form of FieldValue within params * Add ScalarValue, use it as params for esql.query * Change response type to ArrayBuffer * Add type alias ES|QL response body type for consistency * Remove pragmas from the specification as they only are reachable from snapshot builds --------- Co-authored-by: Bogdan Pintea --- specification/_doc_ids/table.csv | 2 + specification/_types/Binary.ts | 3 ++ specification/_types/common.ts | 6 +++ specification/esql/_types/Pragmas.ts | 27 ++++++++++ specification/esql/query/QueryRequest.ts | 65 +++++++++++++++++++++++ specification/esql/query/QueryResponse.ts | 24 +++++++++ specification/tsconfig.json | 1 + 7 files changed, 128 insertions(+) create mode 100644 specification/esql/_types/Pragmas.ts create mode 100644 specification/esql/query/QueryRequest.ts create mode 100644 specification/esql/query/QueryResponse.ts diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 42830bab86..2bee472789 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -121,6 +121,8 @@ eql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ eql-sequences,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html#eql-sequences eql-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html eql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html +esql-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html +esql-query-params,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-rest.html#esql-rest-params evaluate-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/evaluate-dfanalytics.html execute-enrich-policy-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/execute-enrich-policy-api.html expected-reciprocal,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#_expected_reciprocal_rank_err diff --git a/specification/_types/Binary.ts b/specification/_types/Binary.ts index 8bc826754b..56b792ea38 100644 --- a/specification/_types/Binary.ts +++ b/specification/_types/Binary.ts @@ -19,3 +19,6 @@ // Vector tile response export type MapboxVectorTiles = ArrayBuffer + +// ES|QL columns +export type EsqlColumns = ArrayBuffer diff --git a/specification/_types/common.ts b/specification/_types/common.ts index 60aa713a83..732150a2a6 100644 --- a/specification/_types/common.ts +++ b/specification/_types/common.ts @@ -36,6 +36,12 @@ export type FieldValue = | null | UserDefinedValue +/** + * A scalar value. + * @codegen_names long, double, string, boolean, null + */ +export type ScalarValue = long | double | string | boolean | null + export class UrlParameter {} export type Uri = string diff --git a/specification/esql/_types/Pragmas.ts b/specification/esql/_types/Pragmas.ts new file mode 100644 index 0000000000..6ddd71b047 --- /dev/null +++ b/specification/esql/_types/Pragmas.ts @@ -0,0 +1,27 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { integer } from '@_types/Numeric' +import { Duration } from '@_types/Time' + +export enum DataPartitioning { + SHARD, + SEGMENT, + DOC +} diff --git a/specification/esql/query/QueryRequest.ts b/specification/esql/query/QueryRequest.ts new file mode 100644 index 0000000000..844ff4862a --- /dev/null +++ b/specification/esql/query/QueryRequest.ts @@ -0,0 +1,65 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RequestBase } from '@_types/Base' +import { QueryContainer } from '@_types/query_dsl/abstractions' +import { Pragmas } from '@esql/_types/Pragmas' +import { ScalarValue } from '@_types/common' + +/** + * Executes an ES|QL request + * @rest_spec_name esql.query + * @availability stack since=8.11.0 stability=experimental + * @doc_id esql-query + */ +export interface Request extends RequestBase { + query_parameters: { + /** + * A short version of the Accept header, e.g. json, yaml. + */ + format?: string + /** + * The character to use between values within a CSV row. Only valid for the CSV format. + */ + delimiter?: string + } + /** + * Use the `query` element to start a query. Use `time_zone` to specify an execution time zone and `columnar` to format the answer. + */ + body: { + /** + * By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results. + */ + columnar?: boolean + /** + * Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. + */ + filter?: QueryContainer + locale?: string + /** + * To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters. + * @doc_id esql-query-params + */ + params?: Array + /** + * The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results. + */ + query: string + } +} diff --git a/specification/esql/query/QueryResponse.ts b/specification/esql/query/QueryResponse.ts new file mode 100644 index 0000000000..25f71b15be --- /dev/null +++ b/specification/esql/query/QueryResponse.ts @@ -0,0 +1,24 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { EsqlColumns } from '@_types/Binary' + +export class Response { + body: EsqlColumns +} diff --git a/specification/tsconfig.json b/specification/tsconfig.json index 116b45177b..ce641242e8 100644 --- a/specification/tsconfig.json +++ b/specification/tsconfig.json @@ -28,6 +28,7 @@ "@dangling_indices/*": ["dangling_indices/*"], "@enrich/*": ["enrich/*"], "@eql/*": ["eql/*"], + "@esql/*": ["esql/*"], "@features/*": ["features/*"], "@fleet/*": ["fleet/*"], "@graph/*": ["graph/*"],