diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/to_date_nanos.md b/docs/reference/query-languages/esql/_snippets/functions/description/to_date_nanos.md index 3c4d976d90e46..ea3e5d885e159 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/to_date_nanos.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/to_date_nanos.md @@ -5,7 +5,7 @@ Converts an input to a nanosecond-resolution date value (aka date_nanos). ::::{note} -The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attepting to convertvalues outside of that range will result in null with a warning.. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch. +The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch. :::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/cbrt.md b/docs/reference/query-languages/esql/_snippets/functions/examples/cbrt.md index 3b0b23b92517b..5b170eb9b3126 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/cbrt.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/cbrt.md @@ -4,7 +4,7 @@ ```esql ROW d = 1000.0 -| EVAL c = cbrt(d) +| EVAL c = CBRT(d) ``` | d: double | c:double | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md b/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md index 62a3d61e4a5db..327102ad390da 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/date_diff.md @@ -3,7 +3,8 @@ **Examples** ```esql -ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") +ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), + date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") | EVAL dd_ms = DATE_DIFF("microseconds", date1, date2) ``` @@ -15,12 +16,12 @@ When subtracting in calendar units - like year, month a.s.o. - only the fully el To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly. ```esql -ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"), - start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"), - end_24=TO_DATETIME("2024-12-31T23:59:59.999") -| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24) -| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24) -| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24) +ROW end_23 = TO_DATETIME("2023-12-31T23:59:59.999Z"), + start_24 = TO_DATETIME("2024-01-01T00:00:00.000Z"), + end_24 = TO_DATETIME("2024-12-31T23:59:59.999") +| EVAL end23_to_start24 = DATE_DIFF("year", end_23, start_24) +| EVAL end23_to_end24 = DATE_DIFF("year", end_23, end_24) +| EVAL start_to_end_24 = DATE_DIFF("year", start_24, end_24) ``` | end_23:date | start_24:date | end_24:date | end23_to_start24:integer | end23_to_end24:integer | start_to_end_24:integer | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/date_extract.md b/docs/reference/query-languages/esql/_snippets/functions/examples/date_extract.md index 432d67afbe0b0..143a7276d5016 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/date_extract.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/date_extract.md @@ -15,7 +15,8 @@ Find all events that occurred outside of business hours (before 9 AM or after 5P ```esql FROM sample_data -| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 +| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 + AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 ``` | @timestamp:date | client_ip:ip | event_duration:long | message:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/from_base64.md b/docs/reference/query-languages/esql/_snippets/functions/examples/from_base64.md index 04e5d34860e52..ae1c713120e3e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/from_base64.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/from_base64.md @@ -3,8 +3,8 @@ **Example** ```esql -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) +ROW a = "ZWxhc3RpYw==" +| EVAL d = FROM_BASE64(a) ``` | a:keyword | d:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md b/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md index ede555826aa61..fbb08e8a780d7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/ip_prefix.md @@ -3,8 +3,8 @@ **Example** ```esql -row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9") -| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112); +ROW ip4 = to_ip("1.2.3.4"), ip6 = TO_IP("fe80::cae2:65ff:fece:feb9") +| EVAL ip4_prefix = IP_PREFIX(ip4, 24, 0), ip6_prefix = IP_PREFIX(ip6, 0, 112); ``` | ip4:ip | ip6:ip | ip4_prefix:ip | ip6_prefix:ip | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/locate.md b/docs/reference/query-languages/esql/_snippets/functions/examples/locate.md index 4b7615c321af6..2982ce8faf42a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/locate.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/locate.md @@ -3,8 +3,8 @@ **Example** ```esql -row a = "hello" -| eval a_ll = locate(a, "ll") +ROW a = "hello" +| EVAL a_ll = LOCATE(a, "ll") ``` | a:keyword | a_ll:integer | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/log.md b/docs/reference/query-languages/esql/_snippets/functions/examples/log.md index 2d00f2e8c76f4..832934a766578 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/log.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/log.md @@ -12,7 +12,7 @@ ROW base = 2.0, value = 8.0 | 2.0 | 8.0 | 3.0 | ```esql -row value = 100 +ROW value = 100 | EVAL s = LOG(value); ``` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/mv_append.md b/docs/reference/query-languages/esql/_snippets/functions/examples/mv_append.md new file mode 100644 index 0000000000000..e62bc0342d8ab --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/mv_append.md @@ -0,0 +1,18 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Example** + +```esql +FROM employees +| WHERE emp_no == 10039 OR emp_no == 10040 +| SORT emp_no +| EVAL dates = MV_APPEND(birth_date, hire_date) +| KEEP emp_no, birth_date, hire_date, dates +``` + +| emp_no:integer | birth_date:date | hire_date:date | dates:date | +| --- | --- | --- | --- | +| 10039 | 1959-10-01T00:00:00Z | 1988-01-19T00:00:00Z | [1959-10-01T00:00:00Z, 1988-01-19T00:00:00Z] | +| 10040 | null | 1993-02-14T00:00:00Z | null | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_base64.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_base64.md index eec74197e08d2..08e69314e6f56 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_base64.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_base64.md @@ -3,8 +3,8 @@ **Example** ```esql -row a = "elastic" -| eval e = to_base64(a) +ROW a = "elastic" +| EVAL e = TO_BASE64(a) ``` | a:keyword | e:keyword | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_date_nanos.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_date_nanos.md new file mode 100644 index 0000000000000..dba21f8630ecd --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_date_nanos.md @@ -0,0 +1,17 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Example** + +```esql +FROM date_nanos +| WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z") + AND millis > "2000-01-01" +| SORT nanos DESC +``` + +| millis:date | nanos:date_nanos | num:long | +| --- | --- | --- | +| 2023-10-23T12:15:03.360Z | 2023-10-23T12:15:03.360103847Z | 1698063303360103847 | +| 2023-10-23T12:15:03.360Z | 2023-10-23T12:15:03.360103847Z | 1698063303360103847 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_dateperiod.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_dateperiod.md index d5140757760b6..0908f553dfe19 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_dateperiod.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_dateperiod.md @@ -3,7 +3,8 @@ **Example** ```esql -row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days"); +ROW x = "2024-01-01"::datetime +| EVAL y = x + "3 DAYS"::date_period, z = x - TO_DATEPERIOD("3 days"); ``` | x:datetime | y:datetime | z:datetime | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/to_timeduration.md b/docs/reference/query-languages/esql/_snippets/functions/examples/to_timeduration.md index 998e6bbc4282c..31c135079f6a8 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/to_timeduration.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/to_timeduration.md @@ -3,7 +3,8 @@ **Example** ```esql -row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours"); +ROW x = "2024-01-01"::datetime +| EVAL y = x + "3 hours"::time_duration, z = x - TO_TIMEDURATION("3 hours"); ``` | x:datetime | y:datetime | z:datetime | diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/values.md b/docs/reference/query-languages/esql/_snippets/functions/examples/values.md index 07332d9fcada8..dcf38c3cb36f6 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/values.md @@ -3,9 +3,9 @@ **Example** ```esql - FROM employees +FROM employees | EVAL first_letter = SUBSTRING(first_name, 0, 1) -| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter +| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter | SORT first_letter ``` diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md b/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md index 3d1f3c9d827d7..4fec582c84b33 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/weighted_avg.md @@ -4,7 +4,7 @@ ```esql FROM employees -| STATS w_avg = WEIGHTED_AVG(salary, height) by languages +| STATS w_avg = WEIGHTED_AVG(salary, height) BY languages | EVAL w_avg = ROUND(w_avg) | KEEP w_avg, languages | SORT languages diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md index 3f3c13606ab1f..434b0fc4fd98e 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/match.md @@ -2,17 +2,39 @@ **Supported function named parameters** -| name | types | description | -| --- | --- | --- | -| fuzziness | [keyword] | Maximum edit distance allowed for matching. | -| auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true. | -| analyzer | [keyword] | Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the field. If no analyzer is mapped, the index’s default analyzer is used. | -| minimum_should_match | [integer] | Minimum number of clauses that must match for a document to be returned. | -| zero_terms_query | [keyword] | Indicates whether all documents or none are returned if the analyzer removes all tokens, such as when using a stop filter. Defaults to none. | -| boost | [float] | Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0. | -| fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true. | -| fuzzy_rewrite | [keyword] | Method used to rewrite the query. See the rewrite parameter for valid values and more information. If the fuzziness parameter is not 0, the match query uses a fuzzy_rewrite method of top_terms_blended_freqs_${max_expansions} by default. | -| prefix_length | [integer] | Number of beginning characters left unchanged for fuzzy matching. Defaults to 0. | -| lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false. | -| operator | [keyword] | Boolean logic used to interpret text in the query value. Defaults to OR. | -| max_expansions | [integer] | Maximum number of terms to which the query will expand. Defaults to 50. | +`fuzziness` +: (keyword) Maximum edit distance allowed for matching. + +`auto_generate_synonyms_phrase_query` +: (boolean) If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true. + +`analyzer` +: (keyword) Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the field. If no analyzer is mapped, the index’s default analyzer is used. + +`minimum_should_match` +: (integer) Minimum number of clauses that must match for a document to be returned. + +`zero_terms_query` +: (keyword) Indicates whether all documents or none are returned if the analyzer removes all tokens, such as when using a stop filter. Defaults to none. + +`boost` +: (float) Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0. + +`fuzzy_transpositions` +: (boolean) If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true. + +`fuzzy_rewrite` +: (keyword) Method used to rewrite the query. See the rewrite parameter for valid values and more information. If the fuzziness parameter is not 0, the match query uses a fuzzy_rewrite method of top_terms_blended_freqs_${max_expansions} by default. + +`prefix_length` +: (integer) Number of beginning characters left unchanged for fuzzy matching. Defaults to 0. + +`lenient` +: (boolean) If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false. + +`operator` +: (keyword) Boolean logic used to interpret text in the query value. Defaults to OR. + +`max_expansions` +: (integer) Maximum number of terms to which the query will expand. Defaults to 50. + diff --git a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md index bd5f495920052..39d5bf1af00d6 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md +++ b/docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/qstr.md @@ -2,26 +2,66 @@ **Supported function named parameters** -| name | types | description | -| --- | --- | --- | -| max_determinized_states | [integer] | Maximum number of automaton states required for the query. Default is 10000. | -| fuzziness | [keyword] | Maximum edit distance allowed for matching. | -| auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true. | -| phrase_slop | [integer] | Maximum number of positions allowed between matching tokens for phrases. Defaults to 0 (which means exact matches are required). | -| default_field | [keyword] | Default field to search if no field is provided in the query string. Supports wildcards (*). | -| allow_leading_wildcard | [boolean] | If true, the wildcard characters * and ? are allowed as the first character of the query string. Defaults to true. | -| minimum_should_match | [string] | Minimum number of clauses that must match for a document to be returned. | -| fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true. | -| fuzzy_prefix_length | [integer] | Number of beginning characters left unchanged for fuzzy matching. Defaults to 0. | -| time_zone | [keyword] | Coordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query string to UTC. | -| lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false. | -| rewrite | [keyword] | Method used to rewrite the query. | -| default_operator | [keyword] | Default boolean logic used to interpret text in the query string if no operators are specified. | -| analyzer | [keyword] | Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the default_field. | -| fuzzy_max_expansions | [integer] | Maximum number of terms to which the query expands for fuzzy matching. Defaults to 50. | -| quote_analyzer | [keyword] | Analyzer used to convert quoted text in the query string into tokens. Defaults to the search_quote_analyzer mapped for the default_field. | -| allow_wildcard | [boolean] | If true, the query attempts to analyze wildcard terms in the query string. Defaults to false. | -| boost | [float] | Floating point number used to decrease or increase the relevance scores of the query. | -| quote_field_suffix | [keyword] | Suffix appended to quoted text in the query string. | -| enable_position_increments | [boolean] | If true, enable position increments in queries constructed from a query_string search. Defaults to true. | -| fields | [keyword] | Array of fields to search. Supports wildcards (*). | +`max_determinized_states` +: (integer) Maximum number of automaton states required for the query. Default is 10000. + +`fuzziness` +: (keyword) Maximum edit distance allowed for matching. + +`auto_generate_synonyms_phrase_query` +: (boolean) If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true. + +`phrase_slop` +: (integer) Maximum number of positions allowed between matching tokens for phrases. Defaults to 0 (which means exact matches are required). + +`default_field` +: (keyword) Default field to search if no field is provided in the query string. Supports wildcards (*). + +`allow_leading_wildcard` +: (boolean) If true, the wildcard characters * and ? are allowed as the first character of the query string. Defaults to true. + +`minimum_should_match` +: (string) Minimum number of clauses that must match for a document to be returned. + +`fuzzy_transpositions` +: (boolean) If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true. + +`fuzzy_prefix_length` +: (integer) Number of beginning characters left unchanged for fuzzy matching. Defaults to 0. + +`time_zone` +: (keyword) Coordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query string to UTC. + +`lenient` +: (boolean) If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false. + +`rewrite` +: (keyword) Method used to rewrite the query. + +`default_operator` +: (keyword) Default boolean logic used to interpret text in the query string if no operators are specified. + +`analyzer` +: (keyword) Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the default_field. + +`fuzzy_max_expansions` +: (integer) Maximum number of terms to which the query expands for fuzzy matching. Defaults to 50. + +`quote_analyzer` +: (keyword) Analyzer used to convert quoted text in the query string into tokens. Defaults to the search_quote_analyzer mapped for the default_field. + +`allow_wildcard` +: (boolean) If true, the query attempts to analyze wildcard terms in the query string. Defaults to false. + +`boost` +: (float) Floating point number used to decrease or increase the relevance scores of the query. + +`quote_field_suffix` +: (keyword) Suffix appended to quoted text in the query string. + +`enable_position_increments` +: (boolean) If true, enable position increments in queries constructed from a query_string search. Defaults to true. + +`fields` +: (keyword) Array of fields to search. Supports wildcards (*). + diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md b/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md index 68a55dc513205..f9d782d304bfa 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/categorize.md @@ -1,11 +1,11 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `CATEGORIZE` [esql-categorize] -::::{warning} +:::{warning} Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -:::: +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md b/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md index cf61e572cd6cc..b9adaac7f3e50 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/kql.md @@ -1,11 +1,11 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `KQL` [esql-kql] -::::{warning} +:::{warning} Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -:::: +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/match.md b/docs/reference/query-languages/esql/_snippets/functions/layout/match.md index 3dfadc4b6d44d..82d861909abfd 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/match.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/match.md @@ -1,11 +1,15 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `MATCH` [esql-match] -::::{warning} +:::{warning} +###### COMING 9.1.0 + Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -:::: + +Support for optional named parameters is only available from 9.1.0 +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/mv_append.md b/docs/reference/query-languages/esql/_snippets/functions/layout/mv_append.md index 8016115f0e735..a7563570fe309 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/mv_append.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/mv_append.md @@ -18,3 +18,6 @@ :::{include} ../types/mv_append.md ::: + +:::{include} ../examples/mv_append.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md b/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md index f136215b6b701..19f6dda64ef1d 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/qstr.md @@ -1,11 +1,15 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `QSTR` [esql-qstr] -::::{warning} +:::{warning} +###### COMING 9.1.0 + Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -:::: + +Support for optional named parameters is only available from 9.1.0 +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/term.md b/docs/reference/query-languages/esql/_snippets/functions/layout/term.md index fe886f769b84a..64967e792a59c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/term.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/term.md @@ -1,11 +1,11 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `TERM` [esql-term] -::::{warning} +:::{warning} Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -:::: +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/to_aggregate_metric_double.md b/docs/reference/query-languages/esql/_snippets/functions/layout/to_aggregate_metric_double.md index 52439c620383c..ed65b3d386bcd 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/to_aggregate_metric_double.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/to_aggregate_metric_double.md @@ -1,6 +1,9 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `TO_AGGREGATE_METRIC_DOUBLE` [esql-to_aggregate_metric_double] +```{applies_to} +product: COMING 9.1 +``` **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/to_date_nanos.md b/docs/reference/query-languages/esql/_snippets/functions/layout/to_date_nanos.md index 36010b2ced3a9..1142dc727f29a 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/to_date_nanos.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/to_date_nanos.md @@ -18,3 +18,6 @@ :::{include} ../types/to_date_nanos.md ::: + +:::{include} ../examples/to_date_nanos.md +::: diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/to_lower.md b/docs/reference/query-languages/esql/_snippets/functions/layout/to_lower.md index 6bdb4654cb542..0327f8a7579e1 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/to_lower.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/to_lower.md @@ -1,6 +1,11 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `TO_LOWER` [esql-to_lower] +:::{note} +###### COMING 9.1.0 + +Support for multivalued parameters is only available from 9.1.0 +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/to_upper.md b/docs/reference/query-languages/esql/_snippets/functions/layout/to_upper.md index 05d2416dbe0e5..bafcb218a54c9 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/to_upper.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/to_upper.md @@ -1,6 +1,11 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `TO_UPPER` [esql-to_upper] +:::{note} +###### COMING 9.1.0 + +Support for multivalued parameters is only available from 9.1.0 +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/values.md b/docs/reference/query-languages/esql/_snippets/functions/layout/values.md index 4dbd9b6f84c58..9cc069b0c4f58 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/values.md @@ -1,11 +1,13 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ## `VALUES` [esql-values] -::::{warning} +:::{warning} +###### PREVIEW + Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. -:::: +::: **Syntax** diff --git a/docs/reference/query-languages/esql/_snippets/functions/types/to_aggregate_metric_double.md b/docs/reference/query-languages/esql/_snippets/functions/types/to_aggregate_metric_double.md deleted file mode 100644 index cfe51aa1472c1..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/functions/types/to_aggregate_metric_double.md +++ /dev/null @@ -1,8 +0,0 @@ -% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. - -**Supported types** - -| number | result | -| --- | --- | -aggregate_metric_double - diff --git a/docs/reference/query-languages/esql/_snippets/lists/aggregation-functions.md b/docs/reference/query-languages/esql/_snippets/lists/aggregation-functions.md index 421879dd1f067..a2698e9aad583 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/aggregation-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/aggregation-functions.md @@ -11,5 +11,5 @@ * [`STD_DEV`](../../esql-functions-operators.md#esql-std_dev) * [`SUM`](../../esql-functions-operators.md#esql-sum) * [`TOP`](../../esql-functions-operators.md#esql-top) -* [`VALUES`](../../esql-functions-operators.md#esql-values) +* [preview] [`VALUES`](../../esql-functions-operators.md#esql-values) * [`WEIGHTED_AVG`](../../esql-functions-operators.md#esql-weighted_avg) diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/cast.md b/docs/reference/query-languages/esql/_snippets/operators/examples/cast.md index f2b40fc594002..760d1327efd98 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/cast.md +++ b/docs/reference/query-languages/esql/_snippets/operators/examples/cast.md @@ -1,3 +1,5 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + **Example** ```esql @@ -7,3 +9,5 @@ ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION | ver:version | | --- | | 1.2.3 | + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/examples/predicates.md b/docs/reference/query-languages/esql/_snippets/operators/examples/predicates.md index 5185846413bc3..1e3c1cd49305c 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/examples/predicates.md +++ b/docs/reference/query-languages/esql/_snippets/operators/examples/predicates.md @@ -1,3 +1,5 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + **Examples** ```esql @@ -23,3 +25,5 @@ FROM employees | COUNT(emp_no):long | | --- | | 84 | + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/layout/cast.md b/docs/reference/query-languages/esql/_snippets/operators/layout/cast.md index 4dc459c82b139..d0fcda92b6f9e 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/layout/cast.md +++ b/docs/reference/query-languages/esql/_snippets/operators/layout/cast.md @@ -1,5 +1,10 @@ ## `Cast (::)` [esql-cast-operator] +:::{image} ../../../images/operators/cast.svg +:alt: Embedded +:class: text-center +::: + The `::` operator provides a convenient alternative syntax to the TO_ [conversion functions](../../../esql-functions-operators.md#esql-type-conversion-functions). diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/predicates.md b/docs/reference/query-languages/esql/_snippets/operators/types/predicates.md new file mode 100644 index 0000000000000..986c99c3cb457 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/types/predicates.md @@ -0,0 +1,22 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. + +**Supported types** + +| field | result | +| --- | --- | +| boolean | boolean | +| cartesian_point | boolean | +| cartesian_shape | boolean | +| date | boolean | +| date_nanos | boolean | +| double | boolean | +| geo_point | boolean | +| geo_shape | boolean | +| integer | boolean | +| ip | boolean | +| keyword | boolean | +| long | boolean | +| text | boolean | +| unsigned_long | boolean | +| version | boolean | + diff --git a/docs/reference/query-languages/esql/esql-commands.md b/docs/reference/query-languages/esql/esql-commands.md index 9acdf3c482456..c76a5f10299ef 100644 --- a/docs/reference/query-languages/esql/esql-commands.md +++ b/docs/reference/query-languages/esql/esql-commands.md @@ -666,6 +666,10 @@ FROM employees ## `LOOKUP JOIN` [esql-lookup-join] ::::{warning} +```{applies_to} +stack: preview 9.0, coming 9.1 +serverless: preview +``` This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. :::: @@ -747,6 +751,10 @@ FROM Left ## `MV_EXPAND` [esql-mv_expand] ::::{warning} +```{applies_to} +stack: preview 9.0, coming 9.1 +serverless: preview +``` This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. :::: diff --git a/docs/reference/query-languages/esql/images/functions/bucket.svg b/docs/reference/query-languages/esql/images/functions/bucket.svg index 4e34ef16dc027..78694296922ed 100644 --- a/docs/reference/query-languages/esql/images/functions/bucket.svg +++ b/docs/reference/query-languages/esql/images/functions/bucket.svg @@ -1 +1 @@ -BUCKET(field,buckets,from,to) \ No newline at end of file +BUCKET(field,buckets,from,to) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/cidr_match.svg b/docs/reference/query-languages/esql/images/functions/cidr_match.svg index 2ef7896c52a33..dc20093abc382 100644 --- a/docs/reference/query-languages/esql/images/functions/cidr_match.svg +++ b/docs/reference/query-languages/esql/images/functions/cidr_match.svg @@ -1 +1 @@ -CIDR_MATCH(ip,blockX) \ No newline at end of file +CIDR_MATCH(ip,blockX) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/coalesce.svg b/docs/reference/query-languages/esql/images/functions/coalesce.svg index fdd0b501fa2e0..d87603f4dc748 100644 --- a/docs/reference/query-languages/esql/images/functions/coalesce.svg +++ b/docs/reference/query-languages/esql/images/functions/coalesce.svg @@ -1 +1 @@ -COALESCE(first,rest) \ No newline at end of file +COALESCE(first,rest) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/concat.svg b/docs/reference/query-languages/esql/images/functions/concat.svg index edf03d976a4d9..6a39637e2c4fc 100644 --- a/docs/reference/query-languages/esql/images/functions/concat.svg +++ b/docs/reference/query-languages/esql/images/functions/concat.svg @@ -1 +1 @@ -CONCAT(string1,string2) \ No newline at end of file +CONCAT(string1,string2) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/count.svg b/docs/reference/query-languages/esql/images/functions/count.svg index 6bc0d7b15848a..480b947ecaee7 100644 --- a/docs/reference/query-languages/esql/images/functions/count.svg +++ b/docs/reference/query-languages/esql/images/functions/count.svg @@ -1 +1 @@ -COUNT(field) \ No newline at end of file +COUNT(field) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/count_distinct.svg b/docs/reference/query-languages/esql/images/functions/count_distinct.svg index 0e65902fb99b5..a786c02eb4532 100644 --- a/docs/reference/query-languages/esql/images/functions/count_distinct.svg +++ b/docs/reference/query-languages/esql/images/functions/count_distinct.svg @@ -1 +1 @@ -COUNT_DISTINCT(field,precision) \ No newline at end of file +COUNT_DISTINCT(field,precision) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_format.svg b/docs/reference/query-languages/esql/images/functions/date_format.svg index 92081244e669b..a616b55771a6b 100644 --- a/docs/reference/query-languages/esql/images/functions/date_format.svg +++ b/docs/reference/query-languages/esql/images/functions/date_format.svg @@ -1 +1 @@ -DATE_FORMAT(dateFormat,date) \ No newline at end of file +DATE_FORMAT(dateFormat,date) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/date_parse.svg b/docs/reference/query-languages/esql/images/functions/date_parse.svg index 17bfe8607f88e..0f5e5f624143a 100644 --- a/docs/reference/query-languages/esql/images/functions/date_parse.svg +++ b/docs/reference/query-languages/esql/images/functions/date_parse.svg @@ -1 +1 @@ -DATE_PARSE(datePattern,dateString) \ No newline at end of file +DATE_PARSE(datePattern,dateString) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/greatest.svg b/docs/reference/query-languages/esql/images/functions/greatest.svg index d1d98c942f980..64c758a6fb419 100644 --- a/docs/reference/query-languages/esql/images/functions/greatest.svg +++ b/docs/reference/query-languages/esql/images/functions/greatest.svg @@ -1 +1 @@ -GREATEST(first,rest) \ No newline at end of file +GREATEST(first,rest) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/least.svg b/docs/reference/query-languages/esql/images/functions/least.svg index 0e323c09303fe..603be2dd3c513 100644 --- a/docs/reference/query-languages/esql/images/functions/least.svg +++ b/docs/reference/query-languages/esql/images/functions/least.svg @@ -1 +1 @@ -LEAST(first,rest) \ No newline at end of file +LEAST(first,rest) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/locate.svg b/docs/reference/query-languages/esql/images/functions/locate.svg index 011f18cb2995e..e7e7979a4f0be 100644 --- a/docs/reference/query-languages/esql/images/functions/locate.svg +++ b/docs/reference/query-languages/esql/images/functions/locate.svg @@ -1 +1 @@ -LOCATE(string,substring,start) \ No newline at end of file +LOCATE(string,substring,start) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/log.svg b/docs/reference/query-languages/esql/images/functions/log.svg index b042fe0714b08..86c171e5c41ff 100644 --- a/docs/reference/query-languages/esql/images/functions/log.svg +++ b/docs/reference/query-languages/esql/images/functions/log.svg @@ -1 +1 @@ -LOG(base,number) \ No newline at end of file +LOG(base,number) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/match.svg b/docs/reference/query-languages/esql/images/functions/match.svg index 353afb7678350..d3e5c362a1a74 100644 --- a/docs/reference/query-languages/esql/images/functions/match.svg +++ b/docs/reference/query-languages/esql/images/functions/match.svg @@ -1 +1 @@ -MATCH(field,query,options) \ No newline at end of file +MATCH(field,query,options) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_slice.svg b/docs/reference/query-languages/esql/images/functions/mv_slice.svg index 4ddd627ca362c..9696069953957 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_slice.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_slice.svg @@ -1 +1 @@ -MV_SLICE(field,start,end) \ No newline at end of file +MV_SLICE(field,start,end) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_sort.svg b/docs/reference/query-languages/esql/images/functions/mv_sort.svg index 8cebad06fc733..16856a15d15ef 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_sort.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_sort.svg @@ -1 +1 @@ -MV_SORT(field,order) \ No newline at end of file +MV_SORT(field,order) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/mv_zip.svg b/docs/reference/query-languages/esql/images/functions/mv_zip.svg index b055bece1eeb6..3fd89860aeb4e 100644 --- a/docs/reference/query-languages/esql/images/functions/mv_zip.svg +++ b/docs/reference/query-languages/esql/images/functions/mv_zip.svg @@ -1 +1 @@ -MV_ZIP(string1,string2,delim) \ No newline at end of file +MV_ZIP(string1,string2,delim) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/qstr.svg b/docs/reference/query-languages/esql/images/functions/qstr.svg index deae79753afe2..af1fb54d617d1 100644 --- a/docs/reference/query-languages/esql/images/functions/qstr.svg +++ b/docs/reference/query-languages/esql/images/functions/qstr.svg @@ -1 +1 @@ -QSTR(query,options) \ No newline at end of file +QSTR(query,options) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/round.svg b/docs/reference/query-languages/esql/images/functions/round.svg index a735dbe622c60..391f47adb76d7 100644 --- a/docs/reference/query-languages/esql/images/functions/round.svg +++ b/docs/reference/query-languages/esql/images/functions/round.svg @@ -1 +1 @@ -ROUND(number,decimals) \ No newline at end of file +ROUND(number,decimals) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/functions/substring.svg b/docs/reference/query-languages/esql/images/functions/substring.svg index 2bdef6b29599b..9d4eb6ca12fea 100644 --- a/docs/reference/query-languages/esql/images/functions/substring.svg +++ b/docs/reference/query-languages/esql/images/functions/substring.svg @@ -1 +1 @@ -SUBSTRING(string,start,length) \ No newline at end of file +SUBSTRING(string,start,length) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/cast.svg b/docs/reference/query-languages/esql/images/operators/cast.svg new file mode 100644 index 0000000000000..afa7b898c8c70 --- /dev/null +++ b/docs/reference/query-languages/esql/images/operators/cast.svg @@ -0,0 +1 @@ +::v \ No newline at end of file diff --git a/docs/reference/query-languages/esql/images/operators/predicates.svg b/docs/reference/query-languages/esql/images/operators/predicates.svg new file mode 100644 index 0000000000000..2740ff8dc31e6 --- /dev/null +++ b/docs/reference/query-languages/esql/images/operators/predicates.svg @@ -0,0 +1 @@ +IS NULL and IS NOT NULLv \ No newline at end of file diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json b/docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json index dabef9cb91a16..455e467463c64 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/cbrt.json @@ -54,7 +54,7 @@ } ], "examples" : [ - "ROW d = 1000.0\n| EVAL c = cbrt(d)" + "ROW d = 1000.0\n| EVAL c = CBRT(d)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json index f1cec52c17022..905b6ad86e79f 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_diff.json @@ -198,8 +198,8 @@ } ], "examples" : [ - "ROW date1 = TO_DATETIME(\"2023-12-02T11:00:00.000Z\"), date2 = TO_DATETIME(\"2023-12-02T11:00:00.001Z\")\n| EVAL dd_ms = DATE_DIFF(\"microseconds\", date1, date2)", - "ROW end_23=TO_DATETIME(\"2023-12-31T23:59:59.999Z\"),\n start_24=TO_DATETIME(\"2024-01-01T00:00:00.000Z\"),\n end_24=TO_DATETIME(\"2024-12-31T23:59:59.999\")\n| EVAL end23_to_start24=DATE_DIFF(\"year\", end_23, start_24)\n| EVAL end23_to_end24=DATE_DIFF(\"year\", end_23, end_24)\n| EVAL start_to_end_24=DATE_DIFF(\"year\", start_24, end_24)" + "ROW date1 = TO_DATETIME(\"2023-12-02T11:00:00.000Z\"),\n date2 = TO_DATETIME(\"2023-12-02T11:00:00.001Z\")\n| EVAL dd_ms = DATE_DIFF(\"microseconds\", date1, date2)", + "ROW end_23 = TO_DATETIME(\"2023-12-31T23:59:59.999Z\"),\n start_24 = TO_DATETIME(\"2024-01-01T00:00:00.000Z\"),\n end_24 = TO_DATETIME(\"2024-12-31T23:59:59.999\")\n| EVAL end23_to_start24 = DATE_DIFF(\"year\", end_23, start_24)\n| EVAL end23_to_end24 = DATE_DIFF(\"year\", end_23, end_24)\n| EVAL start_to_end_24 = DATE_DIFF(\"year\", start_24, end_24)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json b/docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json index bec2af44728c1..545fb4c4e767f 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/date_extract.json @@ -79,7 +79,7 @@ ], "examples" : [ "ROW date = DATE_PARSE(\"yyyy-MM-dd\", \"2022-05-06\")\n| EVAL year = DATE_EXTRACT(\"year\", date)", - "FROM sample_data\n| WHERE DATE_EXTRACT(\"hour_of_day\", @timestamp) < 9 AND DATE_EXTRACT(\"hour_of_day\", @timestamp) >= 17" + "FROM sample_data\n| WHERE DATE_EXTRACT(\"hour_of_day\", @timestamp) < 9\n AND DATE_EXTRACT(\"hour_of_day\", @timestamp) >= 17" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json b/docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json index 2e0f5e9337d32..aaa5e2125d94e 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/from_base64.json @@ -30,7 +30,7 @@ } ], "examples" : [ - "row a = \"ZWxhc3RpYw==\"\n| eval d = from_base64(a)" + "ROW a = \"ZWxhc3RpYw==\"\n| EVAL d = FROM_BASE64(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json b/docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json index 383a8e4e4a58f..062930059bcee 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/ip_prefix.json @@ -30,7 +30,7 @@ } ], "examples" : [ - "row ip4 = to_ip(\"1.2.3.4\"), ip6 = to_ip(\"fe80::cae2:65ff:fece:feb9\")\n| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112);" + "ROW ip4 = to_ip(\"1.2.3.4\"), ip6 = TO_IP(\"fe80::cae2:65ff:fece:feb9\")\n| EVAL ip4_prefix = IP_PREFIX(ip4, 24, 0), ip6_prefix = IP_PREFIX(ip6, 0, 112);" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/locate.json b/docs/reference/query-languages/esql/kibana/definition/functions/locate.json index 165ff9832ee23..ced3e09ff08e3 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/locate.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/locate.json @@ -174,7 +174,7 @@ } ], "examples" : [ - "row a = \"hello\"\n| eval a_ll = locate(a, \"ll\")" + "ROW a = \"hello\"\n| EVAL a_ll = LOCATE(a, \"ll\")" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/log.json b/docs/reference/query-languages/esql/kibana/definition/functions/log.json index d2aea8e63919d..2745781ceeb7e 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/log.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/log.json @@ -343,7 +343,7 @@ ], "examples" : [ "ROW base = 2.0, value = 8.0\n| EVAL s = LOG(base, value)", - "row value = 100\n| EVAL s = LOG(value);" + "ROW value = 100\n| EVAL s = LOG(value);" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json b/docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json index 164502358e44a..898f2edf23ce9 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/mv_append.json @@ -311,6 +311,9 @@ "returnType" : "version" } ], + "examples" : [ + "FROM employees\n| WHERE emp_no == 10039 OR emp_no == 10040\n| SORT emp_no\n| EVAL dates = MV_APPEND(birth_date, hire_date)\n| KEEP emp_no, birth_date, hire_date, dates" + ], "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json index 64f8f900551b3..9acea64eadef3 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_base64.json @@ -30,7 +30,7 @@ } ], "examples" : [ - "row a = \"elastic\"\n| eval e = to_base64(a)" + "ROW a = \"elastic\"\n| EVAL e = TO_BASE64(a)" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json index fccac7edd232d..4aaea33c36af8 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_date_nanos.json @@ -3,7 +3,7 @@ "type" : "scalar", "name" : "to_date_nanos", "description" : "Converts an input to a nanosecond-resolution date value (aka date_nanos).", - "note" : "The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attepting to convertvalues outside of that range will result in null with a warning.. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.", + "note" : "The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.", "signatures" : [ { "params" : [ @@ -90,6 +90,9 @@ "returnType" : "date_nanos" } ], + "examples" : [ + "FROM date_nanos\n| WHERE MV_MIN(nanos) < TO_DATE_NANOS(\"2023-10-23T12:27:28.948Z\")\n AND millis > \"2000-01-01\"\n| SORT nanos DESC" + ], "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json index ef139c2cd2029..ee5590e221ed6 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_dateperiod.json @@ -42,7 +42,7 @@ } ], "examples" : [ - "row x = \"2024-01-01\"::datetime | eval y = x + \"3 DAYS\"::date_period, z = x - to_dateperiod(\"3 days\");" + "ROW x = \"2024-01-01\"::datetime\n| EVAL y = x + \"3 DAYS\"::date_period, z = x - TO_DATEPERIOD(\"3 days\");" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json b/docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json index 314fe7460393d..02e09919dcd2e 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/to_timeduration.json @@ -42,7 +42,7 @@ } ], "examples" : [ - "row x = \"2024-01-01\"::datetime | eval y = x + \"3 hours\"::time_duration, z = x - to_timeduration(\"3 hours\");" + "ROW x = \"2024-01-01\"::datetime\n| EVAL y = x + \"3 hours\"::time_duration, z = x - TO_TIMEDURATION(\"3 hours\");" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/values.json b/docs/reference/query-languages/esql/kibana/definition/functions/values.json index 7150375988188..5d2237522f2fc 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/values.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/values.json @@ -174,7 +174,7 @@ } ], "examples" : [ - " FROM employees\n| EVAL first_letter = SUBSTRING(first_name, 0, 1)\n| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter\n| SORT first_letter" + "FROM employees\n| EVAL first_letter = SUBSTRING(first_name, 0, 1)\n| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter\n| SORT first_letter" ], "preview" : true, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json b/docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json index 6b0e8bb687df7..cfd66406b0a03 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/weighted_avg.json @@ -168,7 +168,7 @@ } ], "examples" : [ - "FROM employees\n| STATS w_avg = WEIGHTED_AVG(salary, height) by languages\n| EVAL w_avg = ROUND(w_avg)\n| KEEP w_avg, languages\n| SORT languages" + "FROM employees\n| STATS w_avg = WEIGHTED_AVG(salary, height) BY languages\n| EVAL w_avg = ROUND(w_avg)\n| KEEP w_avg, languages\n| SORT languages" ], "preview" : false, "snapshot_only" : false diff --git a/docs/reference/query-languages/esql/kibana/definition/operators/cast.json b/docs/reference/query-languages/esql/kibana/definition/operators/cast.json new file mode 100644 index 0000000000000..4983d8ba2f441 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/definition/operators/cast.json @@ -0,0 +1,13 @@ +{ + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "type" : "operator", + "operator" : "::", + "name" : "cast", + "description" : "The `::` operator provides a convenient alternative syntax to the TO_ [conversion functions](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-type-conversion-functions).", + "signatures" : [ ], + "examples" : [ + "ROW ver = CONCAT((\"0\"::INT + 1)::STRING, \".2.3\")::VERSION" + ], + "preview" : false, + "snapshot_only" : false +} diff --git a/docs/reference/query-languages/esql/kibana/definition/operators/predicates.json b/docs/reference/query-languages/esql/kibana/definition/operators/predicates.json new file mode 100644 index 0000000000000..247e356593b32 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/definition/operators/predicates.json @@ -0,0 +1,195 @@ +{ + "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", + "type" : "operator", + "operator" : "predicates", + "name" : "predicates", + "description" : "For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates:", + "signatures" : [ + { + "params" : [ + { + "name" : "field", + "type" : "boolean", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "cartesian_point", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "cartesian_shape", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "date", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "date_nanos", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "double", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "geo_point", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "geo_shape", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "integer", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "ip", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "keyword", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "long", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "text", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "unsigned_long", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "version", + "optional" : false, + "description" : "Input value. The input can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + } + ], + "examples" : [ + "FROM employees\n| WHERE birth_date IS NULL\n| KEEP first_name, last_name\n| SORT first_name\n| LIMIT 3", + "FROM employees\n| WHERE is_rehired IS NOT NULL\n| STATS COUNT(emp_no)" + ], + "preview" : false, + "snapshot_only" : false +} diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/abs.md b/docs/reference/query-languages/esql/kibana/docs/functions/abs.md index aa3ce9af95076..6ca794c8ee38d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/abs.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/abs.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### ABS Returns the absolute value. -``` +```esql ROW number = -1.0 | EVAL abs_number = ABS(number) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/acos.md b/docs/reference/query-languages/esql/kibana/docs/functions/acos.md index 99757d85534c0..76852b67dc822 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/acos.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/acos.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### ACOS Returns the [arccosine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `n` as an angle, expressed in radians. -``` +```esql ROW a=.9 | EVAL acos=ACOS(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/asin.md b/docs/reference/query-languages/esql/kibana/docs/functions/asin.md index 994fc99d23806..58ca0dbf8190c 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/asin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/asin.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the [arcsine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of the input numeric expression as an angle, expressed in radians. -``` +```esql ROW a=.9 | EVAL asin=ASIN(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/atan.md b/docs/reference/query-languages/esql/kibana/docs/functions/atan.md index 0ffa710117208..ec58452f51b08 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/atan.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/atan.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the [arctangent](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of the input numeric expression as an angle, expressed in radians. -``` +```esql ROW a=12.9 | EVAL atan=ATAN(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/atan2.md b/docs/reference/query-languages/esql/kibana/docs/functions/atan2.md index 68b50a2987329..f23c61d2bfc49 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/atan2.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/atan2.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE The [angle](https://en.wikipedia.org/wiki/Atan2) between the positive x-axis and the ray from the origin to the point (x , y) in the Cartesian plane, expressed in radians. -``` +```esql ROW y=12.9, x=.6 | EVAL atan2=ATAN2(y, x) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/avg.md b/docs/reference/query-languages/esql/kibana/docs/functions/avg.md index f8b386a9a631c..5a2313ba09bdb 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/avg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/avg.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### AVG The average of a numeric field. -``` +```esql FROM employees | STATS AVG(height) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md b/docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md index 2656c92277bef..da567362ec994 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### BIT_LENGTH Returns the bit length of a string. -``` +```esql FROM airports | WHERE country == "India" | KEEP city diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/bucket.md b/docs/reference/query-languages/esql/kibana/docs/functions/bucket.md index 3837b653df0a4..c7e2f48fe3f9e 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/bucket.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/bucket.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Creates groups of values - buckets - out of a datetime or numeric input. The size of the buckets can either be provided directly, or chosen based on a recommended count and values range. -``` +```esql FROM employees | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z" | STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z") diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md b/docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md index 8db81a761af79..f26d1c59a3508 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### BYTE_LENGTH Returns the byte length of a string. -``` +```esql FROM airports | WHERE country == "India" | KEEP city diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/case.md b/docs/reference/query-languages/esql/kibana/docs/functions/case.md index 497119493439b..8f6d508fc5870 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/case.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/case.md @@ -10,7 +10,7 @@ If the number of arguments is odd, the last argument is the default value which is returned when no condition matches. If the number of arguments is even, and no condition matches, the function returns `null`. -``` +```esql FROM employees | EVAL type = CASE( languages <= 1, "monolingual", diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/categorize.md b/docs/reference/query-languages/esql/kibana/docs/functions/categorize.md index b0765767429d0..aeb7885aa9559 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/categorize.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/categorize.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### CATEGORIZE Groups text messages into categories of similarly formatted text values. -``` +```esql FROM sample_data | STATS count=COUNT() BY category=CATEGORIZE(message) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md b/docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md index b8d0b05271a4c..b8b80217b013f 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cbrt.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the cube root of a number. The input can be any numeric value, the return value is always a double. Cube roots of infinities are null. -``` +```esql ROW d = 1000.0 -| EVAL c = cbrt(d) +| EVAL c = CBRT(d) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/ceil.md b/docs/reference/query-languages/esql/kibana/docs/functions/ceil.md index 3e29beba3a100..ff9dad8d87b11 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/ceil.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ceil.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### CEIL Round a number up to the nearest integer. -``` +```esql ROW a=1.8 | EVAL a=CEIL(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md b/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md index f8e81019d9685..ac2dc9c081cea 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cidr_match.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### CIDR_MATCH Returns true if the provided IP is contained in one of the provided CIDR blocks. -``` +```esql FROM hosts | WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") | KEEP card, host, ip0, ip1 diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md b/docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md index 050965c68b2d4..0d69ebf26803d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/coalesce.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### COALESCE Returns the first of its arguments that is not null. If all arguments are null, it returns `null`. -``` +```esql ROW a=null, b="b" | EVAL COALESCE(a, b) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/concat.md b/docs/reference/query-languages/esql/kibana/docs/functions/concat.md index 80af1fb838859..20476ff4f5ff9 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/concat.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/concat.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### CONCAT Concatenates two or more strings. -``` +```esql FROM employees | KEEP first_name, last_name | EVAL fullname = CONCAT(first_name, " ", last_name) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cos.md b/docs/reference/query-languages/esql/kibana/docs/functions/cos.md index 55cc348207545..847895e9eb821 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/cos.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cos.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### COS Returns the [cosine](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. -``` +```esql ROW a=1.8 | EVAL cos=COS(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md b/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md index f42b404b49e38..652205092eff7 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/cosh.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### COSH Returns the [hyperbolic cosine](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. -``` +```esql ROW a=1.8 | EVAL cosh=COSH(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/count.md b/docs/reference/query-languages/esql/kibana/docs/functions/count.md index 2602476e2d1d6..6f2c0c0529807 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/count.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/count.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### COUNT Returns the total number (count) of input values. -``` +```esql FROM employees | STATS COUNT(height) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md b/docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md index 8fbc4bbfa2dfd..de590a9facdcc 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/count_distinct.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### COUNT_DISTINCT Returns the approximate number of distinct values. -``` +```esql FROM hosts | STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md index 750e89e3415b0..5810623648384 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_diff.md @@ -6,7 +6,8 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Subtracts the `startTimestamp` from the `endTimestamp` and returns the difference in multiples of `unit`. If `startTimestamp` is later than the `endTimestamp`, negative values are returned. -``` -ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") +```esql +ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), + date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") | EVAL dd_ms = DATE_DIFF("microseconds", date1, date2) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md index d755dcd1345e3..85ef527699968 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_extract.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### DATE_EXTRACT Extracts parts of a date, like year, month, day, hour. -``` +```esql ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06") | EVAL year = DATE_EXTRACT("year", date) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/date_format.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_format.md index 32732ed077498..7d139fbc8727d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/date_format.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_format.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### DATE_FORMAT Returns a string representation of a date, in the provided format. -``` +```esql FROM employees | KEEP first_name, last_name, hire_date | EVAL hired = DATE_FORMAT("yyyy-MM-dd", hire_date) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md index 665d46bdfb8b8..a51e557809c09 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_parse.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### DATE_PARSE Returns a date by parsing the second argument using the format specified in the first argument. -``` +```esql ROW date_string = "2022-05-06" | EVAL date = DATE_PARSE("yyyy-MM-dd", date_string) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md b/docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md index 4bcc003d21257..8ce5afffc41b8 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/date_trunc.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### DATE_TRUNC Rounds down a date to the closest interval. -``` +```esql FROM employees | KEEP first_name, last_name, hire_date | EVAL year_hired = DATE_TRUNC(1 year, hire_date) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/e.md b/docs/reference/query-languages/esql/kibana/docs/functions/e.md index 8b32227e9ddfb..62fae03da50bb 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/e.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/e.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### E Returns [Euler’s number](https://en.wikipedia.org/wiki/E_(mathematical_constant)). -``` +```esql ROW E() ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md b/docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md index 28534d340cb75..f3de00c2c0905 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ends_with.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### ENDS_WITH Returns a boolean that indicates whether a keyword string ends with another string. -``` +```esql FROM employees | KEEP last_name | EVAL ln_E = ENDS_WITH(last_name, "d") diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/exp.md b/docs/reference/query-languages/esql/kibana/docs/functions/exp.md index 59e42eed216af..0ac093ba71de2 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/exp.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/exp.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### EXP Returns the value of e raised to the power of the given number. -``` +```esql ROW d = 5.0 | EVAL s = EXP(d) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/floor.md b/docs/reference/query-languages/esql/kibana/docs/functions/floor.md index 463a9d7f9a2c8..602a9f28b3f87 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/floor.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/floor.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### FLOOR Round a number down to the nearest integer. -``` +```esql ROW a=1.8 | EVAL a=FLOOR(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md b/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md index 68a1d0ede85f6..3685659ec81d7 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/from_base64.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### FROM_BASE64 Decode a base64 string. -``` -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) +```esql +ROW a = "ZWxhc3RpYw==" +| EVAL d = FROM_BASE64(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/greatest.md b/docs/reference/query-languages/esql/kibana/docs/functions/greatest.md index b9f8ddafc1985..fd117be6de935 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/greatest.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/greatest.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the maximum value from multiple columns. This is similar to [`MV_MAX`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-mv_max) except it is intended to run on multiple columns at once. -``` +```esql ROW a = 10, b = 20 | EVAL g = GREATEST(a, b) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/hash.md b/docs/reference/query-languages/esql/kibana/docs/functions/hash.md index 9c391b5d7bbf8..0b9cedf31c377 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/hash.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/hash.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### HASH Computes the hash of the input using various algorithms such as MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512. -``` +```esql FROM sample_data | WHERE message != "Connection error" | EVAL md5 = hash("md5", message), sha256 = hash("sha256", message) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/hypot.md b/docs/reference/query-languages/esql/kibana/docs/functions/hypot.md index 4dc20ac965eec..2d6ec06799c53 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/hypot.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/hypot.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the hypotenuse of two numbers. The input can be any numeric values, the return value is always a double. Hypotenuses of infinities are null. -``` +```esql ROW a = 3.0, b = 4.0 | EVAL c = HYPOT(a, b) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md b/docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md index 7b6110d03e093..f83d2ea5618cd 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ip_prefix.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### IP_PREFIX Truncates an IP to a given prefix length. -``` -row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9") -| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112); +```esql +ROW ip4 = to_ip("1.2.3.4"), ip6 = TO_IP("fe80::cae2:65ff:fece:feb9") +| EVAL ip4_prefix = IP_PREFIX(ip4, 24, 0), ip6_prefix = IP_PREFIX(ip6, 0, 112); ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/kql.md b/docs/reference/query-languages/esql/kibana/docs/functions/kql.md index 7906cfa920fe1..61f1ceb20ea2a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/kql.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/kql.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### KQL Performs a KQL query. Returns true if the provided KQL query string matches the row. -``` +```esql FROM books | WHERE KQL("author: Faulkner") | KEEP book_no, author diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/least.md b/docs/reference/query-languages/esql/kibana/docs/functions/least.md index b0b1df3173543..030eec6c18e61 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/least.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/least.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### LEAST Returns the minimum value from multiple columns. This is similar to [`MV_MIN`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-mv_min) except it is intended to run on multiple columns at once. -``` +```esql ROW a = 10, b = 20 | EVAL l = LEAST(a, b) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/left.md b/docs/reference/query-languages/esql/kibana/docs/functions/left.md index 1e17bc6dd8609..002e5db559bee 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/left.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/left.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### LEFT Returns the substring that extracts *length* chars from *string* starting from the left. -``` +```esql FROM employees | KEEP last_name | EVAL left = LEFT(last_name, 3) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/length.md b/docs/reference/query-languages/esql/kibana/docs/functions/length.md index 9929c19f3b642..1343a4a765525 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/length.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/length.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### LENGTH Returns the character length of a string. -``` +```esql FROM airports | WHERE country == "India" | KEEP city diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/locate.md b/docs/reference/query-languages/esql/kibana/docs/functions/locate.md index 6a23d7620769c..55ebd702ed4ab 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/locate.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/locate.md @@ -7,7 +7,7 @@ Returns an integer that indicates the position of a keyword substring within ano Returns `0` if the substring cannot be found. Note that string positions start from `1`. -``` -row a = "hello" -| eval a_ll = locate(a, "ll") +```esql +ROW a = "hello" +| EVAL a_ll = LOCATE(a, "ll") ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/log.md b/docs/reference/query-languages/esql/kibana/docs/functions/log.md index 996c8af30dcfa..ab3617bfc5016 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/log.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/log.md @@ -7,7 +7,7 @@ Returns the logarithm of a value to a base. The input can be any numeric value, Logs of zero, negative numbers, and base of one return `null` as well as a warning. -``` +```esql ROW base = 2.0, value = 8.0 | EVAL s = LOG(base, value) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/log10.md b/docs/reference/query-languages/esql/kibana/docs/functions/log10.md index 70b2bf9f2a749..d4947ef815c65 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/log10.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/log10.md @@ -7,7 +7,7 @@ Returns the logarithm of a value to base 10. The input can be any numeric value, Logs of 0 and negative numbers return `null` as well as a warning. -``` +```esql ROW d = 1000.0 | EVAL s = LOG10(d) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md b/docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md index 5f2647169c157..7678780ef1f63 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/ltrim.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### LTRIM Removes leading whitespaces from a string. -``` +```esql ROW message = " some text ", color = " red " | EVAL message = LTRIM(message) | EVAL color = LTRIM(color) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/match.md b/docs/reference/query-languages/esql/kibana/docs/functions/match.md index bca1af2e5b634..1e4bb6ef60321 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/match.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/match.md @@ -16,7 +16,7 @@ For a simplified syntax, you can use the [match operator](https://www.elastic.co `MATCH` returns true if the provided query matches the row. -``` +```esql FROM books | WHERE MATCH(author, "Faulkner") | KEEP book_no, author diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/max.md b/docs/reference/query-languages/esql/kibana/docs/functions/max.md index d732703698493..c4e1c1cf58123 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/max.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/max.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MAX The maximum value of a field. -``` +```esql FROM employees | STATS MAX(languages) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/md5.md b/docs/reference/query-languages/esql/kibana/docs/functions/md5.md index 4e41a98717e6f..db3718bb63054 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/md5.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/md5.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MD5 Computes the MD5 hash of the input. -``` +```esql FROM sample_data | WHERE message != "Connection error" | EVAL md5 = md5(message) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/median.md b/docs/reference/query-languages/esql/kibana/docs/functions/median.md index 20db4275ef645..2a40c1a31387a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/median.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/median.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MEDIAN The value that is greater than half of all values and less than half of all values, also known as the 50% [`PERCENTILE`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-percentile). -``` +```esql FROM employees | STATS MEDIAN(salary), PERCENTILE(salary, 50) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md b/docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md index cf5f8cd3a9610..0553e73119aa5 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md @@ -7,7 +7,7 @@ Returns the median absolute deviation, a measure of variability. It is a robust It is calculated as the median of each data point’s deviation from the median of the entire sample. That is, for a random variable `X`, the median absolute deviation is `median(|median(X) - X|)`. -``` +```esql FROM employees | STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/min.md b/docs/reference/query-languages/esql/kibana/docs/functions/min.md index 4e357ae1a555e..4747ac7e35687 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/min.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/min.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MIN The minimum value of a field. -``` +```esql FROM employees | STATS MIN(languages) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md index d83b12a5c78a4..18d9c96fc7529 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_append.md @@ -5,3 +5,10 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_APPEND Concatenates values of two multi-value fields. +```esql +FROM employees +| WHERE emp_no == 10039 OR emp_no == 10040 +| SORT emp_no +| EVAL dates = MV_APPEND(birth_date, hire_date) +| KEEP emp_no, birth_date, hire_date, dates +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md index 29c19162432a2..fe4702a737d42 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_avg.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_AVG Converts a multivalued field into a single valued field containing the average of all of the values. -``` +```esql ROW a=[3, 5, 1, 6] | EVAL avg_a = MV_AVG(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md index ca38a67b81d00..baeae453939d7 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_concat.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_CONCAT Converts a multivalued string expression into a single valued column containing the concatenation of all values separated by a delimiter. -``` +```esql ROW a=["foo", "zoo", "bar"] | EVAL j = MV_CONCAT(a, ", ") ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md index 619606cff6b36..c88d10af8c17b 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_count.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_COUNT Converts a multivalued expression into a single valued column containing a count of the number of values. -``` +```esql ROW a=["foo", "zoo", "bar"] | EVAL count_a = MV_COUNT(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md index b2b08a17ee8bd..f60ba7e3082fa 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_DEDUPE Remove duplicate values from a multivalued field. -``` +```esql ROW a=["foo", "foo", "bar", "foo"] | EVAL dedupe_a = MV_DEDUPE(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md index 6181b1b8e1702..6f12674ebfda0 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_first.md @@ -7,7 +7,7 @@ Converts a multivalued expression into a single valued column containing the first value. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-split). -``` +```esql ROW a="foo;bar;baz" | EVAL first_a = MV_FIRST(SPLIT(a, ";")) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md index 6e686d62bb6fa..773a5b4a5aeab 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_last.md @@ -7,7 +7,7 @@ Converts a multivalue expression into a single valued column containing the last value. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-split). -``` +```esql ROW a="foo;bar;baz" | EVAL last_a = MV_LAST(SPLIT(a, ";")) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md index c9631ed20bb17..6e092aa52864e 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_max.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_MAX Converts a multivalued expression into a single valued column containing the maximum value. -``` +```esql ROW a=[3, 5, 1] | EVAL max_a = MV_MAX(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md index e8d00213f461c..75d0f3f76f54d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_MEDIAN Converts a multivalued field into a single valued field containing the median value. -``` +```esql ROW a=[3, 5, 1] | EVAL median_a = MV_MEDIAN(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md index 9cdda19127c7c..8cf1e477ea2ec 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md @@ -7,7 +7,7 @@ Converts a multivalued field into a single valued field containing the median ab It is calculated as the median of each data point’s deviation from the median of the entire sample. That is, for a random variable `X`, the median absolute deviation is `median(|median(X) - X|)`. -``` +```esql ROW values = [0, 2, 5, 6] | EVAL median_absolute_deviation = MV_MEDIAN_ABSOLUTE_DEVIATION(values), median = MV_MEDIAN(values) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md index fa659f8086c8e..233386b201ca0 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_min.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_MIN Converts a multivalued expression into a single valued column containing the minimum value. -``` +```esql ROW a=[2, 1] | EVAL min_a = MV_MIN(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md index 202ca5f718874..4fa4edee1540d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_percentile.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_PERCENTILE Converts a multivalued field into a single valued field containing the value at which a certain percentage of observed values occur. -``` +```esql ROW values = [5, 5, 10, 12, 5000] | EVAL p50 = MV_PERCENTILE(values, 50), median = MV_MEDIAN(values) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md index e8e3a1d464e0c..1e71922608911 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_pseries_weighted_sum.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_PSERIES_WEIGHTED_SUM Converts a multivalued expression into a single-valued column by multiplying every element on the input list by its corresponding term in P-Series and computing the sum. -``` +```esql ROW a = [70.0, 45.0, 21.0, 21.0, 21.0] | EVAL sum = MV_PSERIES_WEIGHTED_SUM(a, 1.5) | KEEP sum diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md index c69e13e21d141..583153c505ffc 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_slice.md @@ -7,7 +7,7 @@ Returns a subset of the multivalued field using the start and end index values. This is most useful when reading from a function that emits multivalued columns in a known order like [`SPLIT`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-split) or [`MV_SORT`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-mv_sort). -``` +```esql row a = [1, 2, 2, 3] | eval a1 = mv_slice(a, 1), a2 = mv_slice(a, 2, 3) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md index fe3056cb33ed2..169e62c62e88d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sort.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_SORT Sorts a multivalued field in lexicographical order. -``` +```esql ROW a = [4, 2, -3, 2] | EVAL sa = mv_sort(a), sd = mv_sort(a, "DESC") ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md index de407fe0b3928..8f5befd70f6eb 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_sum.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_SUM Converts a multivalued field into a single valued field containing the sum of all of the values. -``` +```esql ROW a=[3, 5, 6] | EVAL sum_a = MV_SUM(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md b/docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md index 17e37f39ccdfa..fdd0e69e64233 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/mv_zip.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### MV_ZIP Combines the values from two multivalued fields with a delimiter that joins them together. -``` +```esql ROW a = ["x", "y", "z"], b = ["1", "2"] | EVAL c = mv_zip(a, b, "-") | KEEP a, b, c diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/now.md b/docs/reference/query-languages/esql/kibana/docs/functions/now.md index da0c24bfd71dc..cfa75ca8f25a6 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/now.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/now.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### NOW Returns current date and time. -``` +```esql ROW current_date = NOW() ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/percentile.md b/docs/reference/query-languages/esql/kibana/docs/functions/percentile.md index 8e244faa88f5c..2a34080172c0a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/percentile.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/percentile.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### PERCENTILE Returns the value at which a certain percentage of observed values occur. For example, the 95th percentile is the value which is greater than 95% of the observed values and the 50th percentile is the `MEDIAN`. -``` +```esql FROM employees | STATS p0 = PERCENTILE(salary, 0) , p50 = PERCENTILE(salary, 50) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/pi.md b/docs/reference/query-languages/esql/kibana/docs/functions/pi.md index de3803916a40d..907408189a250 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/pi.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/pi.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### PI Returns [Pi](https://en.wikipedia.org/wiki/Pi), the ratio of a circle’s circumference to its diameter. -``` +```esql ROW PI() ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/pow.md b/docs/reference/query-languages/esql/kibana/docs/functions/pow.md index e0a161ef71558..258238b740753 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/pow.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/pow.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### POW Returns the value of `base` raised to the power of `exponent`. -``` +```esql ROW base = 2.0, exponent = 2 | EVAL result = POW(base, exponent) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/qstr.md b/docs/reference/query-languages/esql/kibana/docs/functions/qstr.md index 7138458104f45..331c90b03e465 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/qstr.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/qstr.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### QSTR Performs a [query string query](https://www.elastic.co/docs/reference/elasticsearch/query-languages/query-dsl/query-dsl-query-string-query). Returns true if the provided query string matches the row. -``` +```esql FROM books | WHERE QSTR("author: Faulkner") | KEEP book_no, author diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/repeat.md b/docs/reference/query-languages/esql/kibana/docs/functions/repeat.md index 3b28bbb36685a..2c7d6fbebfa97 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/repeat.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/repeat.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### REPEAT Returns a string constructed by concatenating `string` with itself the specified `number` of times. -``` +```esql ROW a = "Hello!" | EVAL triple_a = REPEAT(a, 3) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/replace.md b/docs/reference/query-languages/esql/kibana/docs/functions/replace.md index 3462f07be4ac4..677a86f70e721 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/replace.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/replace.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE The function substitutes in the string `str` any match of the regular expression `regex` with the replacement string `newStr`. -``` +```esql ROW str = "Hello World" | EVAL str = REPLACE(str, "World", "Universe") | KEEP str diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/reverse.md b/docs/reference/query-languages/esql/kibana/docs/functions/reverse.md index aa083518b19f2..738ecbeb0a62a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/reverse.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/reverse.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### REVERSE Returns a new string representing the input string in reverse order. -``` +```esql ROW message = "Some Text" | EVAL message_reversed = REVERSE(message); ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/right.md b/docs/reference/query-languages/esql/kibana/docs/functions/right.md index 76f3cd7ca51b5..24d4949090be4 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/right.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/right.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### RIGHT Return the substring that extracts *length* chars from *str* starting from the right. -``` +```esql FROM employees | KEEP last_name | EVAL right = RIGHT(last_name, 3) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/round.md b/docs/reference/query-languages/esql/kibana/docs/functions/round.md index d4f7bae9d1582..6dbfd44efad52 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/round.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/round.md @@ -8,7 +8,7 @@ Defaults to 0, which returns the nearest integer. If the precision is a negative number, rounds to the number of digits left of the decimal point. -``` +```esql FROM employees | KEEP first_name, last_name, height | EVAL height_ft = ROUND(height * 3.281, 1) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md b/docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md index 3661a025119fb..24ac2510116d0 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/rtrim.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### RTRIM Removes trailing whitespaces from a string. -``` +```esql ROW message = " some text ", color = " red " | EVAL message = RTRIM(message) | EVAL color = RTRIM(color) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md b/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md index c488be1a70631..05e3289900654 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sha1.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SHA1 Computes the SHA1 hash of the input. -``` +```esql FROM sample_data | WHERE message != "Connection error" | EVAL sha1 = sha1(message) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md b/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md index 8ebd296fae06f..79eb2a7e9935a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sha256.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SHA256 Computes the SHA256 hash of the input. -``` +```esql FROM sample_data | WHERE message != "Connection error" | EVAL sha256 = sha256(message) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/signum.md b/docs/reference/query-languages/esql/kibana/docs/functions/signum.md index ffa3f283794e7..c28fbd8a575ac 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/signum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/signum.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the sign of the given number. It returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. -``` +```esql ROW d = 100.0 | EVAL s = SIGNUM(d) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sin.md b/docs/reference/query-languages/esql/kibana/docs/functions/sin.md index f84b7c49a78ee..2ebf4a8ca514b 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/sin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sin.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SIN Returns the [sine](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. -``` +```esql ROW a=1.8 | EVAL sin=SIN(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md b/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md index b99aa3aac69f4..891bd07860502 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sinh.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SINH Returns the [hyperbolic sine](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. -``` +```esql ROW a=1.8 | EVAL sinh=SINH(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/space.md b/docs/reference/query-languages/esql/kibana/docs/functions/space.md index 72235fd64b5a9..aa6af229d7b89 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/space.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/space.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SPACE Returns a string made of `number` spaces. -``` +```esql ROW message = CONCAT("Hello", SPACE(1), "World!"); ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/split.md b/docs/reference/query-languages/esql/kibana/docs/functions/split.md index 44b6173920490..e50f9641b4824 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/split.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/split.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SPLIT Split a single valued string into multiple strings. -``` +```esql ROW words="foo;bar;baz;qux;quux;corge" | EVAL word = SPLIT(words, ";") ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md b/docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md index c1d34ddbfd13d..ea4eedea14893 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sqrt.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns the square root of a number. The input can be any numeric value, the return value is always a double. Square roots of negative numbers and infinities are null. -``` +```esql ROW d = 100.0 | EVAL s = SQRT(d) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md index bf5a364ce52f1..1c911585101e3 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_centroid_agg.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### ST_CENTROID_AGG Calculate the spatial centroid over a field with spatial point geometry type. -``` +```esql FROM airports | STATS centroid=ST_CENTROID_AGG(location) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md index 32f1c06876fd9..23a263de29656 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_contains.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns whether the first geometry contains the second geometry. This is the inverse of the [ST_WITHIN](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-st_within) function. -``` +```esql FROM airport_city_boundaries | WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))")) | KEEP abbrev, airport, region, city, city_location diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md index 7d8163008a331..a06003547ee90 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_disjoint.md @@ -7,7 +7,7 @@ Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the [ST_INTERSECTS](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-st_intersects) function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅ -``` +```esql FROM airport_city_boundaries | WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))")) | KEEP abbrev, airport, region, city, city_location diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md index c3c4c31dbf514..11d84cef696aa 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_distance.md @@ -7,7 +7,7 @@ Computes the distance between two points. For cartesian geometries, this is the pythagorean distance in the same units as the original coordinates. For geographic geometries, this is the circular distance along the great circle in meters. -``` +```esql FROM airports | WHERE abbrev == "CPH" | EVAL distance = ST_DISTANCE(location, city_location) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md index 4aec58cb7de21..f3c59719f64aa 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_envelope.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### ST_ENVELOPE Determines the minimum bounding box of the supplied geometry. -``` +```esql FROM airport_city_boundaries | WHERE abbrev == "CPH" | EVAL envelope = ST_ENVELOPE(city_boundary) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md index 94bcc420a52da..88d6340ab05b6 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_extent_agg.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### ST_EXTENT_AGG Calculate the spatial extent over a field with geometry type. Returns a bounding box for all values of the field. -``` +```esql FROM airports | WHERE country == "India" | STATS extent = ST_EXTENT_AGG(location) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md index b0b3020420191..966b271572d89 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_intersects.md @@ -9,7 +9,7 @@ They intersect if they have any point in common, including their interior points This is the inverse of the [ST_DISJOINT](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-st_disjoint) function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅ -``` +```esql FROM airports | WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))")) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_within.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_within.md index 00255a7d1e051..cbb062e23f364 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_within.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_within.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Returns whether the first geometry is within the second geometry. This is the inverse of the [ST_CONTAINS](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-st_contains) function. -``` +```esql FROM airport_city_boundaries | WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))")) | KEEP abbrev, airport, region, city, city_location diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_x.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_x.md index f6c8596adda4e..9afffafb1d3e8 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_x.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_x.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Extracts the `x` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `longitude` value. -``` +```esql ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") | EVAL x = ST_X(point), y = ST_Y(point) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md index fdba219c50cfb..2dadcd3bb788d 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmax.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Extracts the maximum value of the `x` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `longitude` value. -``` +```esql FROM airport_city_boundaries | WHERE abbrev == "CPH" | EVAL envelope = ST_ENVELOPE(city_boundary) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md index 287fdb4cbaa35..9a0d87a793963 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_xmin.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Extracts the minimum value of the `x` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `longitude` value. -``` +```esql FROM airport_city_boundaries | WHERE abbrev == "CPH" | EVAL envelope = ST_ENVELOPE(city_boundary) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_y.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_y.md index eadcbe49e8d1b..9b4205bb21780 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_y.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_y.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Extracts the `y` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `latitude` value. -``` +```esql ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)") | EVAL x = ST_X(point), y = ST_Y(point) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md index 5dd8ca52ff71c..e8da55f43338a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymax.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Extracts the maximum value of the `y` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `latitude` value. -``` +```esql FROM airport_city_boundaries | WHERE abbrev == "CPH" | EVAL envelope = ST_ENVELOPE(city_boundary) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md index 0f53004c24d27..1e805e705c339 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/st_ymin.md @@ -6,7 +6,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE Extracts the minimum value of the `y` coordinates from the supplied geometry. If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `latitude` value. -``` +```esql FROM airport_city_boundaries | WHERE abbrev == "CPH" | EVAL envelope = ST_ENVELOPE(city_boundary) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md b/docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md index 51cde3ee47a3c..f024612ed7e2c 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/starts_with.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### STARTS_WITH Returns a boolean that indicates whether a keyword string starts with another string. -``` +```esql FROM employees | KEEP last_name | EVAL ln_S = STARTS_WITH(last_name, "B") diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md b/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md index d22052c5f4305..8bbe5e9aa22c2 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/std_dev.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### STD_DEV The standard deviation of a numeric field. -``` +```esql FROM employees | STATS STD_DEV(height) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/substring.md b/docs/reference/query-languages/esql/kibana/docs/functions/substring.md index 132e4f53f766b..c327042056f44 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/substring.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/substring.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SUBSTRING Returns a substring of a string, specified by a start position and an optional length. -``` +```esql FROM employees | KEEP last_name | EVAL ln_sub = SUBSTRING(last_name, 1, 3) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/sum.md b/docs/reference/query-languages/esql/kibana/docs/functions/sum.md index b1565e1dc783a..f747039ab20cc 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/sum.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/sum.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### SUM The sum of a numeric expression. -``` +```esql FROM employees | STATS SUM(languages) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/tan.md b/docs/reference/query-languages/esql/kibana/docs/functions/tan.md index b6c9d3e488ad7..18f7dfe22575c 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/tan.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/tan.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TAN Returns the [tangent](https://en.wikipedia.org/wiki/Sine_and_cosine) of an angle. -``` +```esql ROW a=1.8 | EVAL tan=TAN(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md b/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md index ecd6ad4131387..0e2eb4af258de 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/tanh.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TANH Returns the [hyperbolic tangent](https://en.wikipedia.org/wiki/Hyperbolic_functions) of a number. -``` +```esql ROW a=1.8 | EVAL tanh=TANH(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/tau.md b/docs/reference/query-languages/esql/kibana/docs/functions/tau.md index 2e30f481a8689..870df3d8aebd4 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/tau.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/tau.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TAU Returns the [ratio](https://tauday.com/tau-manifesto) of a circle’s circumference to its radius. -``` +```esql ROW TAU() ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/term.md b/docs/reference/query-languages/esql/kibana/docs/functions/term.md index 0579684b3a3ea..d28ef2d8f5567 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/term.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/term.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TERM Performs a Term query on the specified field. Returns true if the provided term matches the row. -``` +```esql FROM books | WHERE TERM(author, "gabriel") | KEEP book_no, title diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md index 5b5c80dfee96b..dd3d7878affff 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_base64.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_BASE64 Encode a string to a base64 string. -``` -row a = "elastic" -| eval e = to_base64(a) +```esql +ROW a = "elastic" +| EVAL e = TO_BASE64(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md index d0af2e6613753..dee9dcef082aa 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_boolean.md @@ -8,7 +8,7 @@ A string value of `true` will be case-insensitive converted to the Boolean `true For anything else, including the empty string, the function will return `false`. The numerical value of `0` will be converted to `false`, anything else will be converted to `true`. -``` +```esql ROW str = ["true", "TRuE", "false", "", "yes", "1"] | EVAL bool = TO_BOOLEAN(str) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md index fdcbeb4324cc2..47a06790274c5 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianpoint.md @@ -7,7 +7,7 @@ Converts an input value to a `cartesian_point` value. A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. -``` +```esql ROW wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"] | MV_EXPAND wkt | EVAL pt = TO_CARTESIANPOINT(wkt) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md index d67882252debb..40285e1b0d7f8 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_cartesianshape.md @@ -7,7 +7,7 @@ Converts an input value to a `cartesian_shape` value. A string will only be successfully converted if it respects the [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. -``` +```esql ROW wkt = ["POINT(4297.11 -1475.53)", "POLYGON ((3339584.72 1118889.97, 4452779.63 4865942.27, 2226389.81 4865942.27, 1113194.90 2273030.92, 3339584.72 1118889.97))"] | MV_EXPAND wkt | EVAL geom = TO_CARTESIANSHAPE(wkt) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md index cf08b93b3f4a7..e0537c62d1e37 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md @@ -5,4 +5,10 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_DATE_NANOS Converts an input to a nanosecond-resolution date value (aka date_nanos). -Note: The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attepting to convertvalues outside of that range will result in null with a warning.. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch. +```esql +FROM date_nanos +| WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z") + AND millis > "2000-01-01" +| SORT nanos DESC +``` +Note: The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning. Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch. diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md index 932f3dcbf9240..497d0057f9a13 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_dateperiod.md @@ -5,6 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_DATEPERIOD Converts an input value into a `date_period` value. -``` -row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days"); +```esql +ROW x = "2024-01-01"::datetime +| EVAL y = x + "3 DAYS"::date_period, z = x - TO_DATEPERIOD("3 days"); ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md index a06f541702f23..05812d8f336e8 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md @@ -7,7 +7,7 @@ Converts an input value to a date value. A string will only be successfully converted if it’s respecting the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. To convert dates in other formats, use [`DATE_PARSE`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-date_parse). -``` +```esql ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"] | EVAL datetime = TO_DATETIME(string) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md index 369af66bd00db..703eeee9d7f9c 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_degrees.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_DEGREES Converts a number in [radians](https://en.wikipedia.org/wiki/Radian) to [degrees](https://en.wikipedia.org/wiki/Degree_(angle)). -``` +```esql ROW rad = [1.57, 3.14, 4.71] | EVAL deg = TO_DEGREES(rad) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_double.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_double.md index a567007939bbf..4b7733865560a 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_double.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_double.md @@ -7,7 +7,7 @@ Converts an input value to a double value. If the input parameter is of a date t its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to double. Boolean `true` will be converted to double `1.0`, `false` to `0.0`. -``` +```esql ROW str1 = "5.20128E11", str2 = "foo" | EVAL dbl = TO_DOUBLE("520128000000"), dbl1 = TO_DOUBLE(str1), dbl2 = TO_DOUBLE(str2) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md index 054c4ae31b4ad..4f73435f68bf4 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_geopoint.md @@ -7,7 +7,7 @@ Converts an input value to a `geo_point` value. A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. -``` +```esql ROW wkt = "POINT(42.97109630194 14.7552534413725)" | EVAL pt = TO_GEOPOINT(wkt) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md index de02d6592df84..9c59033e5d1ec 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_geoshape.md @@ -7,7 +7,7 @@ Converts an input value to a `geo_shape` value. A string will only be successfully converted if it respects the [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. -``` +```esql ROW wkt = "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" | EVAL geom = TO_GEOSHAPE(wkt) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md index 87d9ef9efc0fd..9e42a0d8e93d2 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_integer.md @@ -8,7 +8,7 @@ If the input parameter is of a date type, its value will be interpreted as milli since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to integer. Boolean `true` will be converted to integer `1`, `false` to `0`. -``` +```esql ROW long = [5013792, 2147483647, 501379200000] | EVAL int = TO_INTEGER(long) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md index 2b1a862a25fe2..e6490b3546981 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_ip.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_IP Converts an input string to an IP value. -``` +```esql ROW str1 = "1.1.1.1", str2 = "foo" | EVAL ip1 = TO_IP(str1), ip2 = TO_IP(str2) | WHERE CIDR_MATCH(ip1, "1.0.0.0/8") diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_long.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_long.md index 5146351a4eceb..5fc4b5ec152c9 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_long.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_long.md @@ -7,7 +7,7 @@ Converts an input value to a long value. If the input parameter is of a date typ its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to long. Boolean `true` will be converted to long `1`, `false` to `0`. -``` +```esql ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" | EVAL long1 = TO_LONG(str1), long2 = TO_LONG(str2), long3 = TO_LONG(str3) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md index 18791a194c429..0fff52322b7ec 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_lower.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_LOWER Returns a new string representing the input string converted to lower case. -``` +```esql ROW message = "Some Text" | EVAL message_lower = TO_LOWER(message) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md index 9c96e03711294..5cfa5c60dfacc 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_radians.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_RADIANS Converts a number in [degrees](https://en.wikipedia.org/wiki/Degree_(angle)) to [radians](https://en.wikipedia.org/wiki/Radian). -``` +```esql ROW deg = [90.0, 180.0, 270.0] | EVAL rad = TO_RADIANS(deg) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md index 832d79c29fbe9..cab203c05067c 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_string.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_STRING Converts an input value into a string. -``` +```esql ROW a=10 | EVAL j = TO_STRING(a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md index 9554189c6f842..e5511ba2a4f12 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_timeduration.md @@ -5,6 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_TIMEDURATION Converts an input value into a `time_duration` value. -``` -row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours"); +```esql +ROW x = "2024-01-01"::datetime +| EVAL y = x + "3 hours"::time_duration, z = x - TO_TIMEDURATION("3 hours"); ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md index 6dd7123fa49e0..6c58253306994 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_unsigned_long.md @@ -7,7 +7,7 @@ Converts an input value to an unsigned long value. If the input parameter is of its value will be interpreted as milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), converted to unsigned long. Boolean `true` will be converted to unsigned long `1`, `false` to `0`. -``` +```esql ROW str1 = "2147483648", str2 = "2147483648.2", str3 = "foo" | EVAL long1 = TO_UNSIGNED_LONG(str1), long2 = TO_ULONG(str2), long3 = TO_UL(str3) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md index add8fc703fcf1..8735d88dd4e07 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_upper.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_UPPER Returns a new string representing the input string converted to upper case. -``` +```esql ROW message = "Some Text" | EVAL message_upper = TO_UPPER(message) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md b/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md index 8ad51a21b8b6d..42292a8129280 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/to_version.md @@ -5,6 +5,6 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TO_VERSION Converts an input string to a version value. -``` +```esql ROW v = TO_VERSION("1.2.3") ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/top.md b/docs/reference/query-languages/esql/kibana/docs/functions/top.md index a5b1f64e02bc0..f6359061c2016 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/top.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/top.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TOP Collects the top values for a field. Includes repeated values. -``` +```esql FROM employees | STATS top_salaries = TOP(salary, 3, "desc"), top_salary = MAX(salary) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/trim.md b/docs/reference/query-languages/esql/kibana/docs/functions/trim.md index 21045312f1d02..f4c46dc491547 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/trim.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/trim.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### TRIM Removes leading and trailing whitespaces from a string. -``` +```esql ROW message = " some text ", color = " red " | EVAL message = TRIM(message) | EVAL color = TRIM(color) diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/values.md b/docs/reference/query-languages/esql/kibana/docs/functions/values.md index 60140538db269..c1a618733860f 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/values.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/values.md @@ -5,9 +5,9 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### VALUES Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-mv_sort). -``` - FROM employees +```esql +FROM employees | EVAL first_letter = SUBSTRING(first_name, 0, 1) -| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter +| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter | SORT first_letter ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md b/docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md index 39741e8bcc5c6..15b36f8b1dd30 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/weighted_avg.md @@ -5,9 +5,9 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### WEIGHTED_AVG The weighted average of a numeric expression. -``` +```esql FROM employees -| STATS w_avg = WEIGHTED_AVG(salary, height) by languages +| STATS w_avg = WEIGHTED_AVG(salary, height) BY languages | EVAL w_avg = ROUND(w_avg) | KEEP w_avg, languages | SORT languages diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/cast.md b/docs/reference/query-languages/esql/kibana/docs/operators/cast.md new file mode 100644 index 0000000000000..860716afe4771 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/operators/cast.md @@ -0,0 +1,10 @@ + + +### CAST +The `::` operator provides a convenient alternative syntax to the TO_ [conversion functions](https://www.elastic.co/docs/reference/elasticsearch/query-languages/esql/esql-functions-operators#esql-type-conversion-functions). + +```esql +ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/in.md b/docs/reference/query-languages/esql/kibana/docs/operators/in.md index 1a6c54976550b..e3dd2ba252231 100644 --- a/docs/reference/query-languages/esql/kibana/docs/operators/in.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/in.md @@ -5,7 +5,7 @@ This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../RE ### IN The `IN` operator allows testing whether a field or expression equals an element in a list of literals, fields or expressions. -``` +```esql ROW a = 1, b = 4, c = 3 | WHERE c-a IN (3, b / 2, a) ``` diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/like.md b/docs/reference/query-languages/esql/kibana/docs/operators/like.md index 423f4e61e7af7..e0f709b26a823 100644 --- a/docs/reference/query-languages/esql/kibana/docs/operators/like.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/like.md @@ -13,7 +13,7 @@ The following wildcard characters are supported: * `*` matches zero or more characters. * `?` matches one character. -``` +```esql FROM employees | WHERE first_name LIKE """?b*""" | KEEP first_name, last_name diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md b/docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md index 77133408d2a69..9b5a34c2a8780 100644 --- a/docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/match_operator.md @@ -13,7 +13,7 @@ For using the function syntax, or adding [match query parameters](https://www.el `:` returns true if the provided query matches the row. -``` +```esql FROM books | WHERE MATCH(author, "Faulkner") | KEEP book_no, author diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/predicates.md b/docs/reference/query-languages/esql/kibana/docs/operators/predicates.md new file mode 100644 index 0000000000000..bd959656d9815 --- /dev/null +++ b/docs/reference/query-languages/esql/kibana/docs/operators/predicates.md @@ -0,0 +1,14 @@ + + +### PREDICATES +For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates: + +```esql +FROM employees +| WHERE birth_date IS NULL +| KEEP first_name, last_name +| SORT first_name +| LIMIT 3 +``` diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/rlike.md b/docs/reference/query-languages/esql/kibana/docs/operators/rlike.md index d272d36656439..72b34318ee189 100644 --- a/docs/reference/query-languages/esql/kibana/docs/operators/rlike.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/rlike.md @@ -8,7 +8,7 @@ Use `RLIKE` to filter data based on string patterns using using the left-hand side of the operator, but it can also act on a constant (literal) expression. The right-hand side of the operator represents the pattern. -``` +```esql FROM employees | WHERE first_name RLIKE """.leja.*""" | KEEP first_name, last_name diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/convert.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/convert.csv-spec index 68a1f1691b911..ef6afeb45c775 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/convert.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/convert.csv-spec @@ -227,7 +227,8 @@ emp_no:integer | languages:integer | height:double convertToDatePeriod required_capability: cast_string_literal_to_temporal_amount //tag::castToDatePeriod[] -row x = "2024-01-01"::datetime | eval y = x + "3 DAYS"::date_period, z = x - to_dateperiod("3 days"); +ROW x = "2024-01-01"::datetime +| EVAL y = x + "3 DAYS"::date_period, z = x - TO_DATEPERIOD("3 days"); //end::castToDatePeriod[] //tag::castToDatePeriod-result[] @@ -239,7 +240,8 @@ x:datetime |y:datetime |z:datetime convertToTimeDuration required_capability: cast_string_literal_to_temporal_amount //tag::castToTimeDuration[] -row x = "2024-01-01"::datetime | eval y = x + "3 hours"::time_duration, z = x - to_timeduration("3 hours"); +ROW x = "2024-01-01"::datetime +| EVAL y = x + "3 hours"::time_duration, z = x - TO_TIMEDURATION("3 hours"); //end::castToTimeDuration[] //tag::castToTimeDuration-result[] diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date.csv-spec index 1cb4784923e10..34a42695feacf 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date.csv-spec @@ -344,7 +344,8 @@ null docsDateDiff#[skip:-8.12.99, reason:date_diff added in 8.13] // tag::docsDateDiff[] -ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") +ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), + date2 = TO_DATETIME("2023-12-02T11:00:00.001Z") | EVAL dd_ms = DATE_DIFF("microseconds", date1, date2) // end::docsDateDiff[] ; @@ -446,12 +447,12 @@ evalDateDiffYearForDocs required_capability: date_diff_year_calendarial // tag::evalDateDiffYearForDocs[] -ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"), - start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"), - end_24=TO_DATETIME("2024-12-31T23:59:59.999") -| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24) -| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24) -| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24) +ROW end_23 = TO_DATETIME("2023-12-31T23:59:59.999Z"), + start_24 = TO_DATETIME("2024-01-01T00:00:00.000Z"), + end_24 = TO_DATETIME("2024-12-31T23:59:59.999") +| EVAL end23_to_start24 = DATE_DIFF("year", end_23, start_24) +| EVAL end23_to_end24 = DATE_DIFF("year", end_23, end_24) +| EVAL start_to_end_24 = DATE_DIFF("year", start_24, end_24) // end::evalDateDiffYearForDocs[] ; @@ -1023,7 +1024,8 @@ date:date | year:long docsDateExtractBusinessHours // tag::docsDateExtractBusinessHours[] FROM sample_data -| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 +| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 + AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17 // end::docsDateExtractBusinessHours[] ; @@ -1235,16 +1237,20 @@ required_capability: agg_values mvAppendDates required_capability: fn_mv_append +// tag::mv_append_date[] FROM employees | WHERE emp_no == 10039 OR emp_no == 10040 | SORT emp_no -| EVAL dates = mv_append(birth_date, hire_date) +| EVAL dates = MV_APPEND(birth_date, hire_date) | KEEP emp_no, birth_date, hire_date, dates +// end::mv_append_date[] ; +// tag::mv_append_date-result[] emp_no:integer | birth_date:date | hire_date:date | dates:date 10039 | 1959-10-01T00:00:00Z | 1988-01-19T00:00:00Z | [1959-10-01T00:00:00Z, 1988-01-19T00:00:00Z] 10040 | null | 1993-02-14T00:00:00Z | null +// end::mv_append_date-result[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date_nanos.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date_nanos.csv-spec index a41c9b8cd0b16..ed30665c08a94 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date_nanos.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/date_nanos.csv-spec @@ -396,11 +396,19 @@ date nanos less than required_capability: to_date_nanos required_capability: date_nanos_binary_comparison -FROM date_nanos | WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z") AND millis > "2000-01-01" | SORT nanos DESC; +// tag::to_date_nanos[] +FROM date_nanos +| WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z") + AND millis > "2000-01-01" +| SORT nanos DESC +// end::to_date_nanos[] +; +// tag::to_date_nanos-result[] millis:date | nanos:date_nanos | num:long 2023-10-23T12:15:03.360Z | 2023-10-23T12:15:03.360103847Z | 1698063303360103847 2023-10-23T12:15:03.360Z | 2023-10-23T12:15:03.360103847Z | 1698063303360103847 +// end::to_date_nanos-result[] ; date nanos less than millis diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec index ac211c1e6c49a..e8d59628c29fc 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/ip.csv-spec @@ -548,8 +548,8 @@ beta | 127.0.0.1 ipPrefix required_capability: fn_ip_prefix //tag::ipPrefix[] -row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9") -| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112); +ROW ip4 = to_ip("1.2.3.4"), ip6 = TO_IP("fe80::cae2:65ff:fece:feb9") +| EVAL ip4_prefix = IP_PREFIX(ip4, 24, 0), ip6_prefix = IP_PREFIX(ip6, 0, 112); //end::ipPrefix[] //tag::ipPrefix-result[] diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec index dbc2a2e4b5e51..c80827c372eec 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec @@ -237,7 +237,7 @@ base: double | value: double | s:double ; logofNegativeValue#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 2.0, value = -2 +ROW base = 2.0, value = -2 | EVAL s = LOG(base, value); warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded. @@ -248,7 +248,7 @@ base: double | value: integer | s:double ; logofNegativeBase#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = -2, value = 2.0 +ROW base = -2, value = 2.0 | EVAL s = LOG(base, value); warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded. @@ -259,7 +259,7 @@ base: integer | value: double | s:double ; logofBaseOne#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 1, value = 2 +ROW base = 1, value = 2 | EVAL s = LOG(base, value); warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded. @@ -270,7 +270,7 @@ base: integer | value: integer | s:double ; logofZero#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 2.0, value = 0.0 +ROW base = 2.0, value = 0.0 | EVAL s = LOG(base, value); warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded. @@ -281,7 +281,7 @@ base:double | value:double | s:double ; logofNegativeZero#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 2.0, value = -0.0 +ROW base = 2.0, value = -0.0 | EVAL s = LOG(base, value); warning:Line 2:12: evaluation of [LOG(base, value)] failed, treating result as null. Only first 20 failures recorded. @@ -292,7 +292,7 @@ base:double | value:double | s:double ; logofIntLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 10, value = to_long(1000000000000) +ROW base = 10, value = to_long(1000000000000) | EVAL s = LOG(base, value); base:integer | value:long | s:double @@ -300,7 +300,7 @@ base:integer | value:long | s:double ; logofLongInt#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_long(1000000000000), value = 10 +ROW base = to_long(1000000000000), value = 10 | EVAL s = LOG(base, value); base:long | value:integer | s:double @@ -308,7 +308,7 @@ base:long | value:integer | s:double ; logofLongLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_long(1000000000000), value = to_long(1000000000000) +ROW base = to_long(1000000000000), value = to_long(1000000000000) | EVAL s = LOG(base, value); base:long | value:long | s:double @@ -316,7 +316,7 @@ base:long | value:long | s:double ; logofLongDouble#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_long(1000000000000), value = 10.0 +ROW base = to_long(1000000000000), value = 10.0 | EVAL s = LOG(base, value); base:long | value:double | s:double @@ -324,7 +324,7 @@ base:long | value:double | s:double ; logofDoubleLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 10.0, value = to_long(1000000000000) +ROW base = 10.0, value = to_long(1000000000000) | EVAL s = LOG(base, value); base:double | value:long | s:double @@ -332,7 +332,7 @@ base:double | value:long | s:double ; logofLongUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_long(1000000000000), value = to_ul(1000000000000000000) +ROW base = to_long(1000000000000), value = to_ul(1000000000000000000) | EVAL s = LOG(base, value); base:long | value:UNSIGNED_LONG | s:double @@ -340,7 +340,7 @@ base:long | value:UNSIGNED_LONG | s:double ; logofUnsignedLongLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_ul(1000000000000000000), value = to_long(1000000000000) +ROW base = to_ul(1000000000000000000), value = to_long(1000000000000) | EVAL s = LOG(base, value); base:UNSIGNED_LONG | value:long | s:double @@ -348,7 +348,7 @@ base:UNSIGNED_LONG | value:long | s:double ; logofIntUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 10, value = to_ul(1000000000000000000) +ROW base = 10, value = to_ul(1000000000000000000) | EVAL s = LOG(base, value); base:integer | value:UNSIGNED_LONG | s:double @@ -356,7 +356,7 @@ base:integer | value:UNSIGNED_LONG | s:double ; logofUnsignedLongInt#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_ul(1000000000000000000), value = 10 +ROW base = to_ul(1000000000000000000), value = 10 | EVAL s = LOG(base, value); base:UNSIGNED_LONG | value:integer | s:double @@ -364,7 +364,7 @@ base:UNSIGNED_LONG | value:integer | s:double ; logofUnsignedLongUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_ul(1000000000000000000), value = to_ul(1000000000000000000) +ROW base = to_ul(1000000000000000000), value = to_ul(1000000000000000000) | EVAL s = LOG(base, value); base:UNSIGNED_LONG | value:UNSIGNED_LONG | s:double @@ -372,7 +372,7 @@ base:UNSIGNED_LONG | value:UNSIGNED_LONG | s:double ; logofUnsignedLongDouble#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = to_ul(1000000000000000000), value = 1000000000.0 +ROW base = to_ul(1000000000000000000), value = 1000000000.0 | EVAL s = LOG(base, value); base:UNSIGNED_LONG | value:double | s:double @@ -380,7 +380,7 @@ base:UNSIGNED_LONG | value:double | s:double ; logofDoubleUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row base = 10.0, value = to_ul(1000000000000000000) +ROW base = 10.0, value = to_ul(1000000000000000000) | EVAL s = LOG(base, value); base:double | value:UNSIGNED_LONG | s:double @@ -389,7 +389,7 @@ base:double | value:UNSIGNED_LONG | s:double logofInt#[skip:-8.12.99,reason:new scalar function added in 8.13] // tag::logUnary[] -row value = 100 +ROW value = 100 | EVAL s = LOG(value); // end::logUnary[] @@ -400,7 +400,7 @@ value: integer | s:double ; logofLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row value = to_long(1000000000000) +ROW value = to_long(1000000000000) | EVAL s = LOG(value); value: long | s:double @@ -408,7 +408,7 @@ value: long | s:double ; logofUnsignedLong#[skip:-8.12.99,reason:new scalar function added in 8.13] -row value = to_ul(1000000000000000000) +ROW value = to_ul(1000000000000000000) | EVAL s = LOG(value); value: unsigned_long | s:double @@ -416,7 +416,7 @@ value: unsigned_long | s:double ; logofDouble#[skip:-8.12.99,reason:new scalar function added in 8.13] -row value = 1000000000000.0 +ROW value = 1000000000000.0 | EVAL s = LOG(value); value: double | s:double @@ -1350,7 +1350,7 @@ cbrt required_capability: fn_cbrt // tag::cbrt[] ROW d = 1000.0 -| EVAL c = cbrt(d) +| EVAL c = CBRT(d) // end::cbrt[] ; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec index b6c48ac0bb4b9..610baeca91c51 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec @@ -2099,8 +2099,8 @@ FROM employees | STATS min = min(salary) by languages | SORT min + CASE(language weightedAvg required_capability: agg_weighted_avg -from employees -| stats w_avg_1 = weighted_avg(salary, 1), avg = avg(salary), w_avg_2 = weighted_avg(salary, height) +FROM employees +| STATS w_avg_1 = weighted_avg(salary, 1), avg = avg(salary), w_avg_2 = weighted_avg(salary, height) | EVAL w_avg_1 = ROUND(w_avg_1), avg = ROUND(avg), w_avg_2 = ROUND(w_avg_2) ; @@ -2112,7 +2112,7 @@ weightedAvgGrouping required_capability: agg_weighted_avg // tag::weighted-avg[] FROM employees -| STATS w_avg = WEIGHTED_AVG(salary, height) by languages +| STATS w_avg = WEIGHTED_AVG(salary, height) BY languages | EVAL w_avg = ROUND(w_avg) | KEEP w_avg, languages | SORT languages diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec index 67e717a6e9be1..cee1d5c512715 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec @@ -1770,9 +1770,9 @@ valuesGrouped required_capability: agg_values // tag::values-grouped[] - FROM employees +FROM employees | EVAL first_letter = SUBSTRING(first_name, 0, 1) -| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter +| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter | SORT first_letter // end::values-grouped[] ; @@ -1816,8 +1816,8 @@ M | [foo, bar] locate#[skip:-8.13.99,reason:new string function added in 8.14] // tag::locate[] -row a = "hello" -| eval a_ll = locate(a, "ll") +ROW a = "hello" +| EVAL a_ll = LOCATE(a, "ll") // end::locate[] ; @@ -2008,8 +2008,8 @@ base64Encode#[skip:-8.13.99,reason:new base64 function added in 8.14] required_capability: base64_decode_encode // tag::to_base64[] -row a = "elastic" -| eval e = to_base64(a) +ROW a = "elastic" +| EVAL e = TO_BASE64(a) // end::to_base64[] ; @@ -2023,8 +2023,8 @@ base64Decode#[skip:-8.13.99,reason:new base64 function added in 8.14] required_capability: base64_decode_encode // tag::from_base64[] -row a = "ZWxhc3RpYw==" -| eval d = from_base64(a) +ROW a = "ZWxhc3RpYw==" +| EVAL d = FROM_BASE64(a) // end::from_base64[] ; diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/EsqlFunctionRegistry.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/EsqlFunctionRegistry.java index 1d6c4d5344abb..41c2b64004b8f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/EsqlFunctionRegistry.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/EsqlFunctionRegistry.java @@ -467,18 +467,20 @@ public static class ArgSignature { protected final String[] type; protected final String description; protected final boolean optional; + protected final boolean variadic; protected final DataType targetDataType; - public ArgSignature(String name, String[] type, String description, boolean optional, DataType targetDataType) { + public ArgSignature(String name, String[] type, String description, boolean optional, boolean variadic, DataType targetDataType) { this.name = name; this.type = type; this.description = description; this.optional = optional; + this.variadic = variadic; this.targetDataType = targetDataType; } - public ArgSignature(String name, String[] type, String description, boolean optional) { - this(name, type, description, optional, UNSUPPORTED); + public ArgSignature(String name, String[] type, String description, boolean optional, boolean variadic) { + this(name, type, description, optional, variadic, UNSUPPORTED); } public String name() { @@ -530,7 +532,7 @@ public static class MapArgSignature extends ArgSignature { private final Map mapParams; public MapArgSignature(String name, String description, boolean optional, Map mapParams) { - super(name, new String[] { "map" }, description, optional); + super(name, new String[] { "map" }, description, optional, false); this.mapParams = mapParams; } @@ -579,6 +581,13 @@ public List argNames() { return args.stream().map(ArgSignature::name).toList(); } + /** + * The signature of every argument. + */ + public List args() { + return args; + } + /** * The description of every argument. */ @@ -624,24 +633,25 @@ public static FunctionDescription description(FunctionDefinition def) { boolean variadic = false; for (int i = 1; i < params.length; i++) { // skipping 1st argument, the source if (Configuration.class.isAssignableFrom(params[i].getType()) == false) { - variadic |= List.class.isAssignableFrom(params[i].getType()); + boolean isList = List.class.isAssignableFrom(params[i].getType()); + variadic |= isList; MapParam mapParamInfo = params[i].getAnnotation(MapParam.class); // refactor this if (mapParamInfo != null) { args.add(mapParam(mapParamInfo)); } else { Param paramInfo = params[i].getAnnotation(Param.class); - args.add(paramInfo != null ? param(paramInfo) : paramWithoutAnnotation(params[i].getName())); + args.add(paramInfo != null ? param(paramInfo, isList) : paramWithoutAnnotation(params[i].getName())); } } } return new FunctionDescription(def.name(), args, returnType, functionDescription, variadic, functionInfo.type()); } - public static ArgSignature param(Param param) { + public static ArgSignature param(Param param, boolean variadic) { String[] type = removeUnderConstruction(param.type()); String desc = param.description().replace('\n', ' '); DataType targetDataType = getTargetType(type); - return new EsqlFunctionRegistry.ArgSignature(param.name(), type, desc, param.optional(), targetDataType); + return new EsqlFunctionRegistry.ArgSignature(param.name(), type, desc, param.optional(), variadic, targetDataType); } public static ArgSignature mapParam(MapParam mapParam) { @@ -659,7 +669,7 @@ public static ArgSignature mapParam(MapParam mapParam) { } public static ArgSignature paramWithoutAnnotation(String name) { - return new EsqlFunctionRegistry.ArgSignature(name, new String[] { "?" }, "", false, UNSUPPORTED); + return new EsqlFunctionRegistry.ArgSignature(name, new String[] { "?" }, "", false, false, UNSUPPORTED); } /** diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesTo.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesTo.java new file mode 100644 index 0000000000000..8d9fae9761935 --- /dev/null +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesTo.java @@ -0,0 +1,20 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +package org.elasticsearch.xpack.esql.expression.function; + +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +@Retention(RetentionPolicy.RUNTIME) +public @interface FunctionAppliesTo { + FunctionAppliesToLifecycle lifeCycle() default FunctionAppliesToLifecycle.GA; + + String version() default ""; + + String description() default ""; +} diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesToLifecycle.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesToLifecycle.java new file mode 100644 index 0000000000000..351c6d5b19fd7 --- /dev/null +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionAppliesToLifecycle.java @@ -0,0 +1,19 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +package org.elasticsearch.xpack.esql.expression.function; + +public enum FunctionAppliesToLifecycle { + PREVIEW, + BETA, + DEVELOPMENT, + DEPRECATED, + COMING, + DISCONTINUED, + UNAVAILABLE, + GA +} diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java index 5c5c2f26279a0..bcc6f569e514f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java @@ -39,6 +39,11 @@ */ boolean preview() default false; + /** + * Whether this function applies to particular versions of Elasticsearch. + */ + FunctionAppliesTo[] appliesTo() default {}; + /** * The description of the function rendered in the docs and kibana's * json files that drive their IDE-like experience. These should be diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java index 3957a926d9ad2..2c76da4974f43 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/CountDistinct.java @@ -91,7 +91,7 @@ public class CountDistinct extends AggregateFunction implements OptionalArgument algorithm, which counts based on the hashes of the values with some interesting properties: - :::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md + :::{include} /reference/aggregations/_snippets/search-aggregations-metrics-cardinality-aggregation-explanation.md ::: The `COUNT_DISTINCT` function takes an optional second parameter to configure diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java index b8758d3e3885d..4ac79f57dbc17 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Percentile.java @@ -56,7 +56,7 @@ public class Percentile extends NumericAggregate implements SurrogateExpression appendix = """ ### `PERCENTILE` is (usually) approximate [esql-percentile-approximate] - :::{include} /reference/data-analysis/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md + :::{include} /reference/aggregations/_snippets/search-aggregations-metrics-percentile-aggregation-approximate.md ::: ::::{warning} diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java index 5e05c3a448295..7cda030d86039 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java @@ -23,6 +23,8 @@ import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.FunctionType; import org.elasticsearch.xpack.esql.expression.function.Param; @@ -84,7 +86,8 @@ public class Values extends AggregateFunction implements ToAggregator { a [Circuit Breaker Error](docs-content://troubleshoot/elasticsearch/circuit-breaker-errors.md). ::::""", type = FunctionType.AGGREGATE, - examples = @Example(file = "string", tag = "values-grouped") + examples = @Example(file = "string", tag = "values-grouped"), + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW) } ) public Values( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java index 0597d11ea50f8..6e74ca7084d4a 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java @@ -33,6 +33,8 @@ import org.elasticsearch.xpack.esql.core.util.Check; import org.elasticsearch.xpack.esql.core.util.NumericUtils; import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.MapParam; import org.elasticsearch.xpack.esql.expression.function.OptionalArgument; @@ -159,7 +161,13 @@ public class Match extends FullTextFunction implements OptionalArgument, PostAna `MATCH` returns true if the provided query matches the row.""", examples = { @Example(file = "match-function", tag = "match-with-field"), - @Example(file = "match-function", tag = "match-with-named-function-params") } + @Example(file = "match-function", tag = "match-with-named-function-params") }, + appliesTo = { + @FunctionAppliesTo( + lifeCycle = FunctionAppliesToLifecycle.COMING, + version = "9.1.0", + description = "Support for optional named parameters is only available from 9.1.0" + ) } ) public Match( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java index 811b6ff6c6777..d426308eff775 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/QueryString.java @@ -25,6 +25,8 @@ import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.core.type.DataTypeConverter; import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.MapParam; import org.elasticsearch.xpack.esql.expression.function.OptionalArgument; @@ -116,7 +118,13 @@ public class QueryString extends FullTextFunction implements OptionalArgument { + "Returns true if the provided query string matches the row.", examples = { @Example(file = "qstr-function", tag = "qstr-with-field"), - @Example(file = "qstr-function", tag = "qstr-with-options") } + @Example(file = "qstr-function", tag = "qstr-with-options") }, + appliesTo = { + @FunctionAppliesTo( + lifeCycle = FunctionAppliesToLifecycle.COMING, + version = "9.1.0", + description = "Support for optional named parameters is only available from 9.1.0" + ) } ) public QueryString( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToAggregateMetricDouble.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToAggregateMetricDouble.java index 621e35d514bd9..64d9c87baff86 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToAggregateMetricDouble.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToAggregateMetricDouble.java @@ -30,6 +30,8 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo; import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.core.type.DataType; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.Param; import org.elasticsearch.xpack.esql.type.EsqlDataTypeConverter; @@ -62,7 +64,11 @@ public class ToAggregateMetricDouble extends AbstractConvertFunction { ToAggregateMetricDouble::new ); - @FunctionInfo(returnType = "aggregate_metric_double", description = "Encode a numeric to an aggregate_metric_double.") + @FunctionInfo( + returnType = "aggregate_metric_double", + description = "Encode a numeric to an aggregate_metric_double.", + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.COMING, version = "9.1") } + ) public ToAggregateMetricDouble( Source source, @Param( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDateNanos.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDateNanos.java index 6d53562600659..1b5dc4ad119e8 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDateNanos.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDateNanos.java @@ -19,6 +19,7 @@ import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.core.type.DataTypeConverter; +import org.elasticsearch.xpack.esql.expression.function.Example; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.Param; @@ -63,9 +64,10 @@ public class ToDateNanos extends AbstractConvertFunction { @FunctionInfo( returnType = "date_nanos", description = "Converts an input to a nanosecond-resolution date value (aka date_nanos).", - note = "The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attepting to convert" - + "values outside of that range will result in null with a warning.. Additionally, integers cannot be converted into date " - + "nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch." + note = "The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert " + + "values outside of that range will result in null with a warning. Additionally, integers cannot be converted into date " + + "nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.", + examples = { @Example(file = "date_nanos", tag = "to_date_nanos") } ) public ToDateNanos( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvAppend.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvAppend.java index 7ec7d1b9b2eca..c60fb07704e2e 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvAppend.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvAppend.java @@ -25,6 +25,7 @@ import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.core.type.DataType; import org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper; +import org.elasticsearch.xpack.esql.expression.function.Example; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.Param; import org.elasticsearch.xpack.esql.expression.function.scalar.EsqlScalarFunction; @@ -65,7 +66,8 @@ public class MvAppend extends EsqlScalarFunction implements EvaluatorMapper { "long", "unsigned_long", "version" }, - description = "Concatenates values of two multi-value fields." + description = "Concatenates values of two multi-value fields.", + examples = { @Example(file = "date", tag = "mv_append_date") } ) public MvAppend( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToLower.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToLower.java index 875f58d409703..dcb6f637b3b03 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToLower.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToLower.java @@ -15,6 +15,8 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo; import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.Param; import org.elasticsearch.xpack.esql.io.stream.PlanStreamInput; @@ -28,7 +30,13 @@ public class ToLower extends ChangeCase { @FunctionInfo( returnType = { "keyword" }, description = "Returns a new string representing the input string converted to lower case.", - examples = { @Example(file = "string", tag = "to_lower"), @Example(file = "string", tag = "to_lower_mv"), } + examples = { @Example(file = "string", tag = "to_lower"), @Example(file = "string", tag = "to_lower_mv"), }, + appliesTo = { + @FunctionAppliesTo( + lifeCycle = FunctionAppliesToLifecycle.COMING, + version = "9.1.0", + description = "Support for multivalued parameters is only available from 9.1.0" + ) } ) public ToLower(Source source, @Param(name = "str", type = { "keyword", "text" }, description = """ String expression. If `null`, the function returns `null`. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToUpper.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToUpper.java index 880c0ae4e5c8c..14691c80498e2 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToUpper.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ToUpper.java @@ -15,6 +15,8 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo; import org.elasticsearch.xpack.esql.core.tree.Source; import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; +import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; import org.elasticsearch.xpack.esql.expression.function.Param; import org.elasticsearch.xpack.esql.io.stream.PlanStreamInput; @@ -28,7 +30,13 @@ public class ToUpper extends ChangeCase { @FunctionInfo( returnType = { "keyword" }, description = "Returns a new string representing the input string converted to upper case.", - examples = @Example(file = "string", tag = "to_upper") + examples = @Example(file = "string", tag = "to_upper"), + appliesTo = { + @FunctionAppliesTo( + lifeCycle = FunctionAppliesToLifecycle.COMING, + version = "9.1.0", + description = "Support for multivalued parameters is only available from 9.1.0" + ) } ) public ToUpper(Source source, @Param(name = "str", type = { "keyword", "text" }, description = """ String expression. If `null`, the function returns `null`. diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java index aca14300df37a..d6f6b906a5d8f 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java @@ -819,7 +819,7 @@ protected final void assertTypeResolutionFailure(Expression expression) { */ private static Map, DataType> signatures; - static Map, DataType> signatures(Class testClass) { + public static Map, DataType> signatures(Class testClass) { if (signatures != null && classGeneratingSignatures == testClass) { return signatures; } diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java index d0f696619aa93..8181281d04f2f 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java @@ -58,6 +58,7 @@ import java.util.Map; import java.util.Optional; import java.util.function.Function; +import java.util.function.Supplier; import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Collectors; @@ -67,7 +68,6 @@ import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.definition; import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.functionRegistered; import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.shouldHideSignature; -import static org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase.signatures; import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.mapParam; import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.param; import static org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry.paramWithoutAnnotation; @@ -78,11 +78,9 @@ public abstract class DocsV3Support { "% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.\n\n"; static final String PREVIEW_CALLOUT = """ - ::::{warning} Do not use on production environments. This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. - :::: """; static FunctionDocsSupport forFunctions(String name, Class testClass) { @@ -192,7 +190,7 @@ public static void renderNegatedOperator( operatorEntry("match_operator", ":", MatchOperator.class, OperatorCategory.SEARCH) ); - enum OperatorCategory { + public enum OperatorCategory { BINARY, UNARY, LOGICAL, @@ -202,7 +200,7 @@ enum OperatorCategory { SEARCH } - record OperatorConfig(String name, String symbol, Class clazz, OperatorCategory category, boolean variadic) {} + public record OperatorConfig(String name, String symbol, Class clazz, OperatorCategory category, boolean variadic) {} private static Map.Entry operatorEntry( String name, @@ -221,13 +219,13 @@ private static Map.Entry operatorEntry(String name, Stri protected final String category; protected final String name; protected final Logger logger; - protected final Class testClass; + private final Supplier, DataType>> signatures; - private DocsV3Support(String category, String name, Class testClass) { + private DocsV3Support(String category, String name, Class testClass, Supplier, DataType>> signatures) { this.category = category; this.name = name; this.logger = LogManager.getLogger(testClass); - this.testClass = testClass; + this.signatures = signatures; } String replaceLinks(String text) { @@ -315,7 +313,7 @@ private String getLink(String key) { case "search-aggregations-bucket-histogram-aggregation" -> makeLink( key, "", - "/reference/data-analysis/aggregations/search-aggregations-bucket-histogram-aggregation.md" + "/reference/aggregations/search-aggregations-bucket-histogram-aggregation.md" ); default -> throw new IllegalArgumentException("Invalid link key <<" + key + ">>"); }; @@ -380,7 +378,7 @@ private void writeToTempDir(Path dir, String extension, String str) throws IOExc static class FunctionDocsSupport extends DocsV3Support { private FunctionDocsSupport(String name, Class testClass) { - super("functions", name, testClass); + super("functions", name, testClass, () -> AbstractFunctionTestCase.signatures(testClass)); } @Override @@ -397,7 +395,6 @@ protected void renderSignature() throws IOException { @Override protected void renderDocs() throws IOException { FunctionDefinition definition = definition(name); - renderSignature(); EsqlFunctionRegistry.FunctionDescription description = EsqlFunctionRegistry.description(definition); if (name.equals("case")) { /* @@ -409,6 +406,7 @@ protected void renderDocs() throws IOException { "elseValue", trueValue.type(), "The value that’s returned when no condition evaluates to `true`.", + true, true ); description = new EsqlFunctionRegistry.FunctionDescription( @@ -435,32 +433,91 @@ protected void renderDocs() throws IOException { } boolean hasExamples = renderExamples(info); boolean hasAppendix = renderAppendix(info.appendix()); - renderFullLayout(info.preview(), hasExamples, hasAppendix, hasFunctionOptions); + renderFullLayout(info.preview(), info.appliesTo(), hasExamples, hasAppendix, hasFunctionOptions); renderKibanaInlineDocs(name, info); renderKibanaFunctionDefinition(name, info, description.args(), description.variadic()); } private void renderFunctionNamedParams(EsqlFunctionRegistry.MapArgSignature mapArgSignature) throws IOException { - String header = "| name | types | description |\n| --- | --- | --- |"; + StringBuilder rendered = new StringBuilder(DOCS_WARNING + """ + **Supported function named parameters** + + """); - List table = new ArrayList<>(); for (Map.Entry argSignatureEntry : mapArgSignature.mapParams().entrySet()) { - StringBuilder builder = new StringBuilder("| "); EsqlFunctionRegistry.MapEntryArgSignature arg = argSignatureEntry.getValue(); - builder.append(arg.name()).append(" | ").append(arg.type()).append(" | ").append(arg.description()); - table.add(builder.append(" |").toString()); + rendered.append("`").append(arg.name()).append("`\n: "); + var type = arg.type().replaceAll("[\\[\\]]+", ""); + rendered.append("(").append(type).append(") ").append(arg.description()).append("\n\n"); } - String rendered = DOCS_WARNING + """ - **Supported function named parameters** - - """ + header + "\n" + table.stream().collect(Collectors.joining("\n")) + "\n"; logger.info("Writing function named parameters for [{}]:\n{}", name, rendered); - writeToTempSnippetsDir("functionNamedParams", rendered); + writeToTempSnippetsDir("functionNamedParams", rendered.toString()); + } + + private String makeCallout(String type, String text) { + return ":::{" + type + "}\n" + text.trim() + "\n:::\n"; + } + + private String makePreviewText(boolean preview, FunctionAppliesTo[] functionAppliesTos) { + StringBuilder previewDescription = new StringBuilder(); + for (FunctionAppliesTo appliesTo : functionAppliesTos) { + if (appliesTo.description().isEmpty() == false) { + previewDescription.append(appliesTo.description()).append("\n"); + } + preview = preview || appliesTo.lifeCycle() == FunctionAppliesToLifecycle.PREVIEW; + } + String appliesToTextWithAT = appliesToText(functionAppliesTos); + String appliesToText = appliesToTextWithoutAppliesTo(functionAppliesTos); + StringBuilder previewText = new StringBuilder(); + if (preview) { + // We have a preview flag, use the WARNING callout + previewText.append(makeCallout("warning", appliesToText + "\n" + PREVIEW_CALLOUT + "\n" + previewDescription + "\n")); + } else if (previewDescription.isEmpty() == false) { + // We have extra descriptive text, nest inside a NOTE for emphasis + previewText.append(makeCallout("note", appliesToText + "\n" + previewDescription)); + } else if (appliesToTextWithAT.isEmpty() == false) { + // No additional text, just use the plan applies_to syntax + previewText.append(appliesToTextWithAT); + } + return previewText.toString(); + } + + private String appliesToText(FunctionAppliesTo[] functionAppliesTos) { + StringBuilder appliesToText = new StringBuilder(); + if (functionAppliesTos.length > 0) { + appliesToText.append("```{applies_to}\n"); + for (FunctionAppliesTo appliesTo : functionAppliesTos) { + appliesToText.append("product: ") + .append(appliesTo.lifeCycle().name()) + .append(" ") + .append(appliesTo.version()) + .append("\n"); + } + appliesToText.append("```\n"); + } + return appliesToText.toString(); } - private void renderFullLayout(boolean preview, boolean hasExamples, boolean hasAppendix, boolean hasFunctionOptions) - throws IOException { + private String appliesToTextWithoutAppliesTo(FunctionAppliesTo[] functionAppliesTos) { + StringBuilder appliesToText = new StringBuilder(); + if (functionAppliesTos.length > 0) { + appliesToText.append("\n"); + for (FunctionAppliesTo appliesTo : functionAppliesTos) { + appliesToText.append("###### "); + appliesToText.append(appliesTo.lifeCycle().name()).append(" ").append(appliesTo.version()).append("\n"); + } + } + return appliesToText.toString(); + } + + private void renderFullLayout( + boolean preview, + FunctionAppliesTo[] functionAppliesTos, + boolean hasExamples, + boolean hasAppendix, + boolean hasFunctionOptions + ) throws IOException { StringBuilder rendered = new StringBuilder( DOCS_WARNING + """ ## `$UPPER_NAME$` [esql-$NAME$] @@ -475,7 +532,7 @@ private void renderFullLayout(boolean preview, boolean hasExamples, boolean hasA """.replace("$NAME$", name) .replace("$CATEGORY$", category) .replace("$UPPER_NAME$", name.toUpperCase(Locale.ROOT)) - .replace("$PREVIEW_CALLOUT$", preview ? PREVIEW_CALLOUT : "") + .replace("$PREVIEW_CALLOUT$", makePreviewText(preview, functionAppliesTos)) ); for (String section : new String[] { "parameters", "description", "types" }) { rendered.append(addInclude(section)); @@ -502,15 +559,25 @@ private String addInclude(String section) { } } - static class OperatorsDocsSupport extends DocsV3Support { + public static class OperatorsDocsSupport extends DocsV3Support { + private final OperatorConfig op; private OperatorsDocsSupport(String name, Class testClass) { - super("operators", name, testClass); + this(name, testClass, OPERATORS.get(name), () -> AbstractFunctionTestCase.signatures(testClass)); + } + + public OperatorsDocsSupport( + String name, + Class testClass, + OperatorConfig op, + Supplier, DataType>> signatures + ) { + super("operators", name, testClass, signatures); + this.op = op; } @Override - protected void renderSignature() throws IOException { - OperatorConfig op = OPERATORS.get(name); + public void renderSignature() throws IOException { String rendered = (switch (op.category()) { case BINARY -> RailRoadDiagram.binaryOperator(op.symbol()); case UNARY -> RailRoadDiagram.unaryOperator(op.symbol()); @@ -526,8 +593,7 @@ protected void renderSignature() throws IOException { } @Override - protected void renderDocs() throws IOException { - DocsV3Support.OperatorConfig op = OPERATORS.get(name); + public void renderDocs() throws IOException { Constructor ctor = constructorWithFunctionInfo(op.clazz()); if (ctor != null) { FunctionInfo functionInfo = ctor.getAnnotation(FunctionInfo.class); @@ -565,6 +631,11 @@ public boolean preview() { return orig.preview(); } + @Override + public FunctionAppliesTo[] appliesTo() { + return orig.appliesTo(); + } + @Override public String description() { return description.apply(orig.description().replace(baseName, name)); @@ -612,7 +683,7 @@ void renderDocsForOperators(String name, Constructor ctor, FunctionInfo info, args.add(mapParam(mapParamInfo)); } else { Param paramInfo = params[i].getAnnotation(Param.class); - args.add(paramInfo != null ? param(paramInfo) : paramWithoutAnnotation(params[i].getName())); + args.add(paramInfo != null ? param(paramInfo, false) : paramWithoutAnnotation(params[i].getName())); } } } @@ -672,8 +743,7 @@ void renderTypes(String name, List args) thro separator.append("--- |"); List table = new ArrayList<>(); - var signatures = signatures(testClass); - for (Map.Entry, DataType> sig : signatures(testClass).entrySet()) { // TODO flip to using sortedSignatures + for (Map.Entry, DataType> sig : this.signatures.get().entrySet()) { // TODO flip to using sortedSignatures if (shouldHideSignature(sig.getKey(), sig.getValue())) { continue; } @@ -698,7 +768,8 @@ void renderTypes(String name, List args) thro } Collections.sort(table); if (table.isEmpty()) { - table.add(signatures.values().iterator().next().esNameIfPossible()); + logger.info("Warning: No table of types generated for [{}]", name); + return; } String rendered = DOCS_WARNING + """ @@ -775,7 +846,7 @@ void renderKibanaInlineDocs(String name, FunctionInfo info) throws IOException { if (info.examples().length > 0) { Example example = info.examples()[0]; - builder.append("```\n"); + builder.append("```esql\n"); builder.append(loadExample(example.file(), example.tag())); builder.append("\n```\n"); } @@ -820,7 +891,7 @@ void renderKibanaFunctionDefinition(String name, FunctionInfo info, List false == a.optional()).count(); @@ -887,7 +958,7 @@ private String removeAsciidocLinks(String asciidoc) { } private List, DataType>> sortedSignatures() { - List, DataType>> sortedSignatures = new ArrayList<>(signatures(testClass).entrySet()); + List, DataType>> sortedSignatures = new ArrayList<>(signatures.get().entrySet()); Collections.sort(sortedSignatures, (lhs, rhs) -> { int maxlen = Math.max(lhs.getKey().size(), rhs.getKey().size()); for (int i = 0; i < maxlen; i++) { diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java index dfec2a563b429..95997564ff7f4 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java @@ -56,27 +56,62 @@ static String functionSignature(FunctionDefinition definition) throws IOExceptio expressions.add(new Repetition(seq, 1, null)); expressions.add(new Repetition(new Literal("elseValue"), 0, 1)); } else { - boolean first = true; - List args = EsqlFunctionRegistry.description(definition).argNames(); - for (String arg : args) { - if (arg.endsWith("...")) { - expressions.add( - new Repetition(new Sequence(new Syntax(","), new Literal(arg.substring(0, arg.length() - 3))), 0, null) - ); + List argExpressions = new ArrayList<>(); + List args = EsqlFunctionRegistry.description(definition).args(); + for (int i = 0; i < args.size(); i++) { + EsqlFunctionRegistry.ArgSignature arg = args.get(i); + String argName = arg.name(); + if (arg.variadic) { + if (argName.endsWith("...")) { + argName = argName.substring(0, argName.length() - 3); + } + argExpressions.add(new Repetition(new Sequence(new Syntax(","), new Literal(argName)), arg.optional ? 0 : 1, null)); } else { - if (first) { - first = false; + if (arg.optional) { + if (definition.name().equals("bucket")) { + // BUCKET requires optional args to be optional together, so we need custom code to do that + var nextArg = args.get(++i); + assert nextArg.optional(); + Sequence seq = new Sequence(new Literal(argName), new Syntax(","), new Literal(nextArg.name)); + argExpressions.add(new Repetition(seq, 0, 1)); + } else if (i < args.size() - 1 && args.get(i + 1).optional() == false) { + // Special case with leading optional args + Sequence seq = new Sequence(new Literal(argName), new Syntax(",")); + argExpressions.add(new Repetition(seq, 0, 1)); + } else { + argExpressions.add(new Repetition(new Literal(argName), 0, 1)); + } } else { - expressions.add(new Syntax(",")); + argExpressions.add(new Literal(argName)); } - expressions.add(new Literal(arg)); } } + expressions.addAll(injectCommas(argExpressions, new Syntax(","))); } expressions.add(new Syntax(")")); return toSvg(new Sequence(expressions.toArray(Expression[]::new))); } + public static List injectCommas(List original, Expression comma) { + List result = new ArrayList<>(); + for (int i = 0; i < original.size(); i++) { + result.add(original.get(i)); + if (i < original.size() - 1 && hasComma(original.get(i), true) == false && hasComma(original.get(i + 1), false) == false) { + result.add(comma); + } + } + return result; + } + + private static boolean hasComma(Expression exp, boolean atEnd) { + if (exp instanceof Repetition rep && rep.getExpression() instanceof Sequence seq) { + Expression[] seqExp = seq.getExpressions(); + int index = atEnd ? seqExp.length - 1 : 0; + return seqExp[index] instanceof Syntax syntax && syntax.text.equals(","); + } + return false; + } + /** * Generate a railroad diagram for binary operator. The output would look like * {@code lhs + rhs}. diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/CastOperatorTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/CastOperatorTests.java new file mode 100644 index 0000000000000..97f2d02f07c9b --- /dev/null +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/CastOperatorTests.java @@ -0,0 +1,84 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +package org.elasticsearch.xpack.esql.expression.predicate.operator; + +import org.elasticsearch.test.ESTestCase; +import org.elasticsearch.xpack.esql.core.expression.Expression; +import org.elasticsearch.xpack.esql.core.type.DataType; +import org.elasticsearch.xpack.esql.expression.function.DocsV3Support; +import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; +import org.elasticsearch.xpack.esql.expression.function.Param; +import org.junit.AfterClass; + +import java.io.IOException; +import java.util.List; +import java.util.Map; + +public class CastOperatorTests extends ESTestCase { + public void testDummy() { + assert true; + } + + @AfterClass + public static void renderDocs() throws IOException { + if (System.getProperty("generateDocs") == null) { + return; + } + DocsV3Support.OperatorConfig op = new DocsV3Support.OperatorConfig( + "cast", + "::", + TestCastOperator.class, + DocsV3Support.OperatorCategory.UNARY, + false + ); + var docs = new DocsV3Support.OperatorsDocsSupport("cast", CastOperatorTests.class, op, CastOperatorTests::signatures); + docs.renderSignature(); + docs.renderDocs(); + } + + public static Map, DataType> signatures() { + // The cast operator cannot produce sensible signatures unless we consider the type as an extra parameter + return Map.of(); + } + + /** + * This class only exists to provide FunctionInfo for the documentation + */ + public class TestCastOperator { + @FunctionInfo( + operator = "::", + returnType = {}, + description = "The `::` operator provides a convenient alternative syntax to the TO_ " + + "[conversion functions](/reference/query-languages/esql/esql-functions-operators.md#esql-type-conversion-functions).", + examples = { @Example(file = "convert", tag = "docsCastOperator") } + ) + public TestCastOperator( + @Param( + name = "field", + type = { + "boolean", + "cartesian_point", + "cartesian_shape", + "date", + "date_nanos", + "double", + "geo_point", + "geo_shape", + "integer", + "ip", + "keyword", + "long", + "text", + "unsigned_long", + "version" }, + description = "Input value. The input can be a single- or multi-valued column or an expression." + ) Expression v + ) {} + } +} diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/NullPredicatesTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/NullPredicatesTests.java new file mode 100644 index 0000000000000..674a7fe77f586 --- /dev/null +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/NullPredicatesTests.java @@ -0,0 +1,95 @@ +/* + * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one + * or more contributor license agreements. Licensed under the Elastic License + * 2.0; you may not use this file except in compliance with the Elastic License + * 2.0. + */ + +package org.elasticsearch.xpack.esql.expression.predicate.operator; + +import org.elasticsearch.test.ESTestCase; +import org.elasticsearch.xpack.esql.core.expression.Expression; +import org.elasticsearch.xpack.esql.core.type.DataType; +import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase; +import org.elasticsearch.xpack.esql.expression.function.DocsV3Support; +import org.elasticsearch.xpack.esql.expression.function.Example; +import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; +import org.elasticsearch.xpack.esql.expression.function.Param; +import org.elasticsearch.xpack.esql.expression.function.scalar.convert.ToStringTests; +import org.junit.AfterClass; + +import java.io.IOException; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * In the documentation we document `IS NULL` and `IS NOT NULL` together. + */ +public class NullPredicatesTests extends ESTestCase { + public void testDummy() { + assert true; + } + + @AfterClass + public static void renderDocs() throws IOException { + if (System.getProperty("generateDocs") == null) { + return; + } + DocsV3Support.OperatorConfig op = new DocsV3Support.OperatorConfig( + "predicates", + "IS NULL and IS NOT NULL", + TestCastOperator.class, + DocsV3Support.OperatorCategory.UNARY, + false + ); + var docs = new DocsV3Support.OperatorsDocsSupport("predicates", NullPredicatesTests.class, op, NullPredicatesTests::signatures); + docs.renderSignature(); + docs.renderDocs(); + } + + public static Map, DataType> signatures() { + // TODO: Verify the correct datatypes for this + Map, DataType> toString = AbstractFunctionTestCase.signatures(ToStringTests.class); + Map, DataType> results = new LinkedHashMap<>(); + for (var entry : toString.entrySet()) { + DataType dataType = entry.getKey().getFirst(); + results.put(List.of(dataType), DataType.BOOLEAN); + } + return results; + } + + /** + * This class only exists to provide FunctionInfo for the documentation + */ + public class TestCastOperator { + @FunctionInfo( + operator = "predicates", + returnType = {}, + description = "For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates:", + examples = { @Example(file = "null", tag = "is-null"), @Example(file = "null", tag = "is-not-null") } + ) + public TestCastOperator( + @Param( + name = "field", + type = { + "boolean", + "cartesian_point", + "cartesian_shape", + "date", + "date_nanos", + "double", + "geo_point", + "geo_shape", + "integer", + "ip", + "keyword", + "long", + "text", + "unsigned_long", + "version" }, + description = "Input value. The input can be a single- or multi-valued column or an expression." + ) Expression v + ) {} + } +}