Initial version of ES|QL query endpoint (#2354)

Anaethelion · Bogdan Pintea · web-flow · commit 747f81216037 · 2023-11-28T15:05:10.000+01:00
* 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 &lt;pintea@mailbox.org&gt;

* 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 &lt;pintea@mailbox.org&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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<ScalarValue>
+    /**
+     * 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
@@ -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
@@ -28,6 +28,7 @@
       "@dangling_indices/*": ["dangling_indices/*"],
       "@enrich/*": ["enrich/*"],
       "@eql/*": ["eql/*"],
+      "@esql/*": ["esql/*"],
       "@features/*": ["features/*"],
       "@fleet/*": ["fleet/*"],
       "@graph/*": ["graph/*"],
