From a003a41f5d90dc38381c69570e9278ce1f6eeea4 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Fri, 19 Jul 2024 06:02:56 -0400 Subject: [PATCH] ESQL: define the `tables` parameter (#2706) Adds support for the tables parameter and documents the profile option. --- output/openapi/elasticsearch-openapi.json | 94 ++++++++ .../elasticsearch-serverless-openapi.json | 94 ++++++++ output/schema/schema-serverless.json | 226 +++++++++++++++++- output/schema/schema.json | 226 +++++++++++++++++- output/typescript/types.ts | 16 ++ .../esql/_types/TableValuesContainer.ts | 33 +++ specification/esql/query/QueryRequest.ts | 13 + 7 files changed, 700 insertions(+), 2 deletions(-) create mode 100644 specification/esql/_types/TableValuesContainer.ts diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 7c0daf8946..02d0f90233 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -8191,11 +8191,22 @@ } }, "profile": { + "description": "If provided and `true` the response will include an extra `profile` object\nwith information on how the query was executed. This information is for human debugging\nand its format can change at any time but it can give some insight into the performance\nof each part of the query.", "type": "boolean" }, "query": { "description": "The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.", "type": "string" + }, + "tables": { + "description": "Tables to use with the LOOKUP operation. The top level key is the table\nname and the next level key is the column name.", + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/esql._types:TableValuesContainer" + } + } } }, "required": [ @@ -80080,6 +80091,89 @@ "head" ] }, + "esql._types:TableValuesContainer": { + "type": "object", + "properties": { + "integer": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesIntegerValue" + } + }, + "keyword": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesKeywordValue" + } + }, + "long": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesLongValue" + } + }, + "double": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesLongDouble" + } + } + }, + "minProperties": 1, + "maxProperties": 1 + }, + "esql._types:TableValuesIntegerValue": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "array", + "items": { + "type": "number" + } + } + ] + }, + "esql._types:TableValuesKeywordValue": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "esql._types:TableValuesLongValue": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "array", + "items": { + "type": "number" + } + } + ] + }, + "esql._types:TableValuesLongDouble": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "array", + "items": { + "type": "number" + } + } + ] + }, "_types:EsqlColumns": { "type": "object" }, diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 249ef9c57e..738bd2a411 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -5471,11 +5471,22 @@ } }, "profile": { + "description": "If provided and `true` the response will include an extra `profile` object\nwith information on how the query was executed. This information is for human debugging\nand its format can change at any time but it can give some insight into the performance\nof each part of the query.", "type": "boolean" }, "query": { "description": "The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.", "type": "string" + }, + "tables": { + "description": "Tables to use with the LOOKUP operation. The top level key is the table\nname and the next level key is the column name.", + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/esql._types:TableValuesContainer" + } + } } }, "required": [ @@ -52323,6 +52334,89 @@ "head" ] }, + "esql._types:TableValuesContainer": { + "type": "object", + "properties": { + "integer": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesIntegerValue" + } + }, + "keyword": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesKeywordValue" + } + }, + "long": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesLongValue" + } + }, + "double": { + "type": "array", + "items": { + "$ref": "#/components/schemas/esql._types:TableValuesLongDouble" + } + } + }, + "minProperties": 1, + "maxProperties": 1 + }, + "esql._types:TableValuesIntegerValue": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "array", + "items": { + "type": "number" + } + } + ] + }, + "esql._types:TableValuesKeywordValue": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "esql._types:TableValuesLongValue": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "array", + "items": { + "type": "number" + } + } + ] + }, + "esql._types:TableValuesLongDouble": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "array", + "items": { + "type": "number" + } + } + ] + }, "_types:EsqlColumns": { "type": "object" }, diff --git a/output/schema/schema-serverless.json b/output/schema/schema-serverless.json index 15d3f9ab33..1a4a04ea3d 100644 --- a/output/schema/schema-serverless.json +++ b/output/schema/schema-serverless.json @@ -17803,6 +17803,7 @@ } }, { + "description": "If provided and `true` the response will include an extra `profile` object\nwith information on how the query was executed. This information is for human debugging\nand its format can change at any time but it can give some insight into the performance\nof each part of the query.", "name": "profile", "required": false, "type": { @@ -17824,6 +17825,40 @@ "namespace": "_builtins" } } + }, + { + "description": "Tables to use with the LOOKUP operation. The top level key is the table\nname and the next level key is the column name.", + "name": "tables", + "required": false, + "type": { + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + "kind": "dictionary_of", + "singleKey": false, + "value": { + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + "kind": "dictionary_of", + "singleKey": false, + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesContainer", + "namespace": "esql._types" + } + } + } + } } ] }, @@ -17879,7 +17914,7 @@ } } ], - "specLocation": "esql/query/QueryRequest.ts#L24-L76" + "specLocation": "esql/query/QueryRequest.ts#L26-L89" }, { "body": { @@ -89128,6 +89163,126 @@ }, "specLocation": "eql/search/types.ts#L20-L32" }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesIntegerValue", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L30-L30", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + } + ], + "kind": "union_of" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesKeywordValue", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L31-L31", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + } + ], + "kind": "union_of" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesLongDouble", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L33-L33", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + } + ], + "kind": "union_of" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesLongValue", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L32-L32", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "long", + "namespace": "_types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "long", + "namespace": "_types" + } + } + } + ], + "kind": "union_of" + } + }, { "kind": "type_alias", "name": { @@ -113217,6 +113372,75 @@ ], "specLocation": "eql/_types/EqlHits.ts#L56-L64" }, + { + "kind": "interface", + "name": { + "name": "TableValuesContainer", + "namespace": "esql._types" + }, + "properties": [ + { + "name": "integer", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesIntegerValue", + "namespace": "esql._types" + } + } + } + }, + { + "name": "keyword", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesKeywordValue", + "namespace": "esql._types" + } + } + } + }, + { + "name": "long", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesLongValue", + "namespace": "esql._types" + } + } + } + }, + { + "name": "double", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesLongDouble", + "namespace": "esql._types" + } + } + } + } + ], + "specLocation": "esql/_types/TableValuesContainer.ts#L22-L28", + "variants": { + "kind": "container" + } + }, { "kind": "interface", "name": { diff --git a/output/schema/schema.json b/output/schema/schema.json index c9a00ca46d..b0d751ed8b 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -112687,6 +112687,195 @@ }, "specLocation": "eql/search/types.ts#L20-L32" }, + { + "kind": "interface", + "name": { + "name": "TableValuesContainer", + "namespace": "esql._types" + }, + "properties": [ + { + "name": "integer", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesIntegerValue", + "namespace": "esql._types" + } + } + } + }, + { + "name": "keyword", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesKeywordValue", + "namespace": "esql._types" + } + } + } + }, + { + "name": "long", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesLongValue", + "namespace": "esql._types" + } + } + } + }, + { + "name": "double", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesLongDouble", + "namespace": "esql._types" + } + } + } + } + ], + "specLocation": "esql/_types/TableValuesContainer.ts#L22-L28", + "variants": { + "kind": "container" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesIntegerValue", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L30-L30", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + } + ], + "kind": "union_of" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesKeywordValue", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L31-L31", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + } + ], + "kind": "union_of" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesLongDouble", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L33-L33", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "double", + "namespace": "_types" + } + } + } + ], + "kind": "union_of" + } + }, + { + "kind": "type_alias", + "name": { + "name": "TableValuesLongValue", + "namespace": "esql._types" + }, + "specLocation": "esql/_types/TableValuesContainer.ts#L32-L32", + "type": { + "items": [ + { + "kind": "instance_of", + "type": { + "name": "long", + "namespace": "_types" + } + }, + { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "long", + "namespace": "_types" + } + } + } + ], + "kind": "union_of" + } + }, { "attachedBehaviors": [ "CommonQueryParameters" @@ -112747,6 +112936,7 @@ } }, { + "description": "If provided and `true` the response will include an extra `profile` object\nwith information on how the query was executed. This information is for human debugging\nand its format can change at any time but it can give some insight into the performance\nof each part of the query.", "name": "profile", "required": false, "type": { @@ -112768,6 +112958,40 @@ "namespace": "_builtins" } } + }, + { + "description": "Tables to use with the LOOKUP operation. The top level key is the table\nname and the next level key is the column name.", + "name": "tables", + "required": false, + "type": { + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + "kind": "dictionary_of", + "singleKey": false, + "value": { + "key": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + }, + "kind": "dictionary_of", + "singleKey": false, + "value": { + "kind": "instance_of", + "type": { + "name": "TableValuesContainer", + "namespace": "esql._types" + } + } + } + } } ] }, @@ -112823,7 +113047,7 @@ } } ], - "specLocation": "esql/query/QueryRequest.ts#L24-L76" + "specLocation": "esql/query/QueryRequest.ts#L26-L89" }, { "body": { diff --git a/output/typescript/types.ts b/output/typescript/types.ts index e128bc14cf..c2ecf989e5 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -9891,6 +9891,21 @@ export type EqlSearchResponse = EqlEqlSearchResponseBase> } } diff --git a/specification/esql/_types/TableValuesContainer.ts b/specification/esql/_types/TableValuesContainer.ts new file mode 100644 index 0000000000..eb5eadd002 --- /dev/null +++ b/specification/esql/_types/TableValuesContainer.ts @@ -0,0 +1,33 @@ +/* + * 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 { double, integer, long } from '@_types/Numeric' + +/** @variants container */ +export interface TableValuesContainer { + integer?: TableValuesIntegerValue[] + keyword?: TableValuesKeywordValue[] + long?: TableValuesLongValue[] + double?: TableValuesLongDouble[] +} + +type TableValuesIntegerValue = integer | integer[] +type TableValuesKeywordValue = string | string[] +type TableValuesLongValue = long | long[] +type TableValuesLongDouble = double | double[] diff --git a/specification/esql/query/QueryRequest.ts b/specification/esql/query/QueryRequest.ts index a9eae673b6..8f73012632 100644 --- a/specification/esql/query/QueryRequest.ts +++ b/specification/esql/query/QueryRequest.ts @@ -17,9 +17,11 @@ * under the License. */ +import { Dictionary } from '@spec_utils/Dictionary' import { RequestBase } from '@_types/Base' import { QueryContainer } from '@_types/query_dsl/abstractions' import { FieldValue } from '@_types/common' +import { TableValuesContainer } from '@esql/_types/TableValuesContainer' /** * Executes an ES|QL request @@ -67,10 +69,21 @@ export interface Request extends RequestBase { * @doc_id esql-query-params */ params?: Array + /** + * If provided and `true` the response will include an extra `profile` object + * with information on how the query was executed. This information is for human debugging + * and its format can change at any time but it can give some insight into the performance + * of each part of the query. + */ profile?: boolean /** * The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results. */ query: string + /** + * Tables to use with the LOOKUP operation. The top level key is the table + * name and the next level key is the column name. + */ + tables?: Dictionary> } }