From e87c49cb4bdb7ee537d18f09a15abc16b82405b3 Mon Sep 17 00:00:00 2001 From: Abdon Pijpelink Date: Thu, 25 Jan 2024 16:32:24 +0100 Subject: [PATCH] [DOCS] Improve ES|QL functions reference for functions E-Z (#104623) * Functions E-Z * Incorporate changes from #103686 * More functions * More functions * Update docs/reference/esql/functions/floor.asciidoc Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> * Update docs/reference/esql/functions/left.asciidoc Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Alexander Spies * Review feedback * Fix geo_shape description * Change 'colum'/'field' into 'expressions' * Review feedback * One more --------- Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Co-authored-by: Alexander Spies Co-authored-by: Elastic Machine --- docs/reference/esql/functions/asin.asciidoc | 5 +- docs/reference/esql/functions/atan.asciidoc | 5 +- docs/reference/esql/functions/atan2.asciidoc | 5 +- .../esql/functions/auto_bucket.asciidoc | 4 +- docs/reference/esql/functions/avg.asciidoc | 8 ++-- docs/reference/esql/functions/cos.asciidoc | 4 +- docs/reference/esql/functions/cosh.asciidoc | 9 ++-- .../esql/functions/count-distinct.asciidoc | 18 ++++--- docs/reference/esql/functions/e.asciidoc | 9 +++- .../esql/functions/ends_with.asciidoc | 25 ++++++++-- docs/reference/esql/functions/floor.asciidoc | 30 ++++++++---- .../esql/functions/greatest.asciidoc | 35 ++++++++++---- docs/reference/esql/functions/least.asciidoc | 35 ++++++++++---- docs/reference/esql/functions/left.asciidoc | 26 ++++++++-- docs/reference/esql/functions/length.asciidoc | 27 +++++++++-- docs/reference/esql/functions/log10.asciidoc | 24 +++++++--- docs/reference/esql/functions/ltrim.asciidoc | 22 +++++++-- docs/reference/esql/functions/max.asciidoc | 19 +++++++- .../median-absolute-deviation.asciidoc | 43 ++++++++++++----- docs/reference/esql/functions/median.asciidoc | 33 +++++++++---- docs/reference/esql/functions/min.asciidoc | 19 +++++++- docs/reference/esql/functions/mv_avg.asciidoc | 28 +++++++++-- .../esql/functions/mv_concat.asciidoc | 29 ++++++++--- .../esql/functions/mv_count.asciidoc | 24 +++++++--- .../esql/functions/mv_dedupe.asciidoc | 26 +++++++--- .../esql/functions/mv_first.asciidoc | 37 +++++++++----- .../reference/esql/functions/mv_last.asciidoc | 37 +++++++++----- docs/reference/esql/functions/mv_max.asciidoc | 27 ++++++++--- .../esql/functions/mv_median.asciidoc | 28 +++++++++-- docs/reference/esql/functions/mv_min.asciidoc | 27 ++++++++--- docs/reference/esql/functions/mv_sum.asciidoc | 25 ++++++++-- docs/reference/esql/functions/now.asciidoc | 21 +++++++- .../esql/functions/percentile.asciidoc | 37 ++++++++++---- docs/reference/esql/functions/pi.asciidoc | 9 +++- docs/reference/esql/functions/pow.asciidoc | 36 ++++++++------ .../reference/esql/functions/replace.asciidoc | 33 +++++++++++-- docs/reference/esql/functions/right.asciidoc | 26 ++++++++-- docs/reference/esql/functions/round.asciidoc | 21 ++++++++ docs/reference/esql/functions/rtrim.asciidoc | 20 ++++++-- docs/reference/esql/functions/sin.asciidoc | 23 +++++++-- docs/reference/esql/functions/sinh.asciidoc | 22 +++++++-- docs/reference/esql/functions/split.asciidoc | 31 ++++++++---- docs/reference/esql/functions/sqrt.asciidoc | 27 ++++++++--- .../esql/functions/starts_with.asciidoc | 25 ++++++++-- .../esql/functions/substring.asciidoc | 30 +++++++++++- docs/reference/esql/functions/sum.asciidoc | 17 ++++++- docs/reference/esql/functions/tan.asciidoc | 23 +++++++-- docs/reference/esql/functions/tanh.asciidoc | 22 +++++++-- docs/reference/esql/functions/tau.asciidoc | 10 +++- .../esql/functions/to_boolean.asciidoc | 38 +++++++++++---- .../esql/functions/to_cartesianpoint.asciidoc | 30 ++++++++---- .../esql/functions/to_cartesianshape.asciidoc | 29 ++++++++--- .../esql/functions/to_datetime.asciidoc | 37 ++++++++++---- .../esql/functions/to_degrees.asciidoc | 26 ++++++++-- .../esql/functions/to_double.asciidoc | 48 ++++++++++++------- .../esql/functions/to_geopoint.asciidoc | 29 ++++++++--- .../esql/functions/to_geoshape.asciidoc | 31 ++++++++---- .../esql/functions/to_integer.asciidoc | 40 +++++++++++----- docs/reference/esql/functions/to_ip.asciidoc | 27 ++++++++--- .../reference/esql/functions/to_long.asciidoc | 34 +++++++++---- .../esql/functions/to_lower.asciidoc | 22 +++++++-- .../esql/functions/to_radians.asciidoc | 26 ++++++++-- .../esql/functions/to_string.asciidoc | 26 +++++++--- .../esql/functions/to_unsigned_long.asciidoc | 41 +++++++++++----- .../esql/functions/to_upper.asciidoc | 22 +++++++-- .../esql/functions/to_version.asciidoc | 30 ++++++++---- docs/reference/esql/functions/trim.asciidoc | 20 ++++++-- .../esql/processing-commands/where.asciidoc | 8 ++++ .../src/main/resources/date.csv-spec | 26 ++++++++++ .../src/main/resources/eval.csv-spec | 18 +++++++ 70 files changed, 1330 insertions(+), 404 deletions(-) diff --git a/docs/reference/esql/functions/asin.asciidoc b/docs/reference/esql/functions/asin.asciidoc index 222f6879785ef..a326852e9b016 100644 --- a/docs/reference/esql/functions/asin.asciidoc +++ b/docs/reference/esql/functions/asin.asciidoc @@ -14,9 +14,8 @@ Numeric expression. If `null`, the function returns `null`. *Description* -Returns the -https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine] -of the input numeric expression as an angle, expressed in radians. +Returns the {wikipedia}/Inverse_trigonometric_functions[arcsine] of the input +numeric expression as an angle, expressed in radians. *Supported types* diff --git a/docs/reference/esql/functions/atan.asciidoc b/docs/reference/esql/functions/atan.asciidoc index bdbbd07cbba60..604fc4d0bbecc 100644 --- a/docs/reference/esql/functions/atan.asciidoc +++ b/docs/reference/esql/functions/atan.asciidoc @@ -14,9 +14,8 @@ Numeric expression. If `null`, the function returns `null`. *Description* -Returns the -https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of the -input numeric expression as an angle, expressed in radians. +Returns the {wikipedia}/Inverse_trigonometric_functions[arctangent] of the input +numeric expression as an angle, expressed in radians. *Supported types* diff --git a/docs/reference/esql/functions/atan2.asciidoc b/docs/reference/esql/functions/atan2.asciidoc index 3ecc0ff86fe26..1920b4b7ac1a0 100644 --- a/docs/reference/esql/functions/atan2.asciidoc +++ b/docs/reference/esql/functions/atan2.asciidoc @@ -17,9 +17,8 @@ Numeric expression. If `null`, the function returns `null`. *Description* -The https://en.wikipedia.org/wiki/Atan2[angle] between the positive x-axis and -the ray from the origin to the point (x , y) in the Cartesian plane, expressed -in radians. +The {wikipedia}/Atan2[angle] between the positive x-axis and the ray from the +origin to the point (x , y) in the Cartesian plane, expressed in radians. *Supported types* diff --git a/docs/reference/esql/functions/auto_bucket.asciidoc b/docs/reference/esql/functions/auto_bucket.asciidoc index 2301939cf5050..aedfdaa7c0e12 100644 --- a/docs/reference/esql/functions/auto_bucket.asciidoc +++ b/docs/reference/esql/functions/auto_bucket.asciidoc @@ -6,13 +6,13 @@ [source,esql] ---- -AUTO_BUCKET(field, buckets, from, to) +AUTO_BUCKET(expression, buckets, from, to) ---- *Parameters* `field`:: -Numeric or date column from which to derive buckets. +Numeric or date expression from which to derive buckets. `buckets`:: Target number of buckets. diff --git a/docs/reference/esql/functions/avg.asciidoc b/docs/reference/esql/functions/avg.asciidoc index 6345be99c5d6d..9a6f5a82d1959 100644 --- a/docs/reference/esql/functions/avg.asciidoc +++ b/docs/reference/esql/functions/avg.asciidoc @@ -6,15 +6,15 @@ [source,esql] ---- -AVG(column) +AVG(expression) ---- -`column`:: -Numeric column. If `null`, the function returns `null`. +`expression`:: +Numeric expression. If `null`, the function returns `null`. *Description* -The average of a numeric field. +The average of a numeric expression. *Supported types* diff --git a/docs/reference/esql/functions/cos.asciidoc b/docs/reference/esql/functions/cos.asciidoc index f7874d46c558a..a5a0251bbd70a 100644 --- a/docs/reference/esql/functions/cos.asciidoc +++ b/docs/reference/esql/functions/cos.asciidoc @@ -14,8 +14,8 @@ Numeric expression. If `null`, the function returns `null`. *Description* -Returns the https://en.wikipedia.org/wiki/Sine_and_cosine[cosine] of `n`. Input -expected in radians. +Returns the {wikipedia}/Sine_and_cosine[cosine] of `n`. Input expected in +radians. *Supported types* diff --git a/docs/reference/esql/functions/cosh.asciidoc b/docs/reference/esql/functions/cosh.asciidoc index ae813e91ec9bb..5883bc4b9d0c4 100644 --- a/docs/reference/esql/functions/cosh.asciidoc +++ b/docs/reference/esql/functions/cosh.asciidoc @@ -12,14 +12,13 @@ image::esql/functions/signature/cosh.svg[Embedded,opts=inline] `n`:: Numeric expression. If `null`, the function returns `null`. -*Supported types* +*Description* -include::types/cosh.asciidoc[] +Returns the {wikipedia}/Hyperbolic_functions[hyperbolic cosine]. -*Description* +*Supported types* -Returns the https://en.wikipedia.org/wiki/Hyperbolic_functions[hyperbolic -cosine]. +include::types/cosh.asciidoc[] *Example* diff --git a/docs/reference/esql/functions/count-distinct.asciidoc b/docs/reference/esql/functions/count-distinct.asciidoc index 14fa6eff39d4c..04a200935cd48 100644 --- a/docs/reference/esql/functions/count-distinct.asciidoc +++ b/docs/reference/esql/functions/count-distinct.asciidoc @@ -6,7 +6,7 @@ [source,esql] ---- -COUNT_DISTINCT(column[, precision]) +COUNT_DISTINCT(column[, precision_threshold]) ---- *Parameters* @@ -14,8 +14,10 @@ COUNT_DISTINCT(column[, precision]) `column`:: Column for which to count the number of distinct values. -`precision`:: -Precision. Refer to <>. +`precision_threshold`:: +Precision threshold. Refer to <>. The +maximum supported value is 40000. Thresholds above this number will have the +same effect as a threshold of 40000. The default value is 3000. *Description* @@ -37,8 +39,12 @@ properties: include::../../aggregations/metrics/cardinality-aggregation.asciidoc[tag=explanation] -The `COUNT_DISTINCT` function takes an optional second parameter to configure the -precision. +The `COUNT_DISTINCT` function takes an optional second parameter to configure +the precision threshold. The precision_threshold options allows to trade memory +for accuracy, and defines a unique count below which counts are expected to be +close to accurate. Above this value, counts might become a bit more fuzzy. The +maximum supported value is 40000, thresholds above this number will have the +same effect as a threshold of 40000. The default value is `3000`. *Supported types* @@ -55,7 +61,7 @@ include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct] include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-result] |=== -With the optional second parameter to configure the precision: +With the optional second parameter to configure the precision threshold: [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/e.asciidoc b/docs/reference/esql/functions/e.asciidoc index 56bf97fd01740..ac082c1a68a07 100644 --- a/docs/reference/esql/functions/e.asciidoc +++ b/docs/reference/esql/functions/e.asciidoc @@ -1,10 +1,17 @@ [discrete] [[esql-e]] === `E` + +*Syntax* + [.text-center] image::esql/functions/signature/e.svg[Embedded,opts=inline] -{wikipedia}/E_(mathematical_constant)[Euler's number]. +*Description* + +Returns {wikipedia}/E_(mathematical_constant)[Euler's number]. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/ends_with.asciidoc b/docs/reference/esql/functions/ends_with.asciidoc index fd2d99931163a..49477996ada19 100644 --- a/docs/reference/esql/functions/ends_with.asciidoc +++ b/docs/reference/esql/functions/ends_with.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-ends_with]] === `ENDS_WITH` + +*Syntax* + [.text-center] image::esql/functions/signature/ends_with.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`suffix`:: +String expression. If `null`, the function returns `null`. + +*Description* + Returns a boolean that indicates whether a keyword string ends with another -string: +string. + +*Supported types* + +include::types/ends_with.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=endsWith] |=== include::{esql-specs}/string.csv-spec[tag=endsWith-result] |=== - -Supported types: - -include::types/ends_with.asciidoc[] diff --git a/docs/reference/esql/functions/floor.asciidoc b/docs/reference/esql/functions/floor.asciidoc index 109033bb18827..0730a87e595fd 100644 --- a/docs/reference/esql/functions/floor.asciidoc +++ b/docs/reference/esql/functions/floor.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-floor]] === `FLOOR` + +*Syntax* + [.text-center] image::esql/functions/signature/floor.svg[Embedded,opts=inline] -Round a number down to the nearest integer. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Rounds a number down to the nearest integer. + +NOTE: This is a noop for `long` (including unsigned) and `integer`. + For `double` this picks the closest `double` value to the integer + similar to {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor]. + +*Supported types* + +include::types/floor.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,11 +34,3 @@ include::{esql-specs}/math.csv-spec[tag=floor] |=== include::{esql-specs}/math.csv-spec[tag=floor-result] |=== - -NOTE: This is a noop for `long` (including unsigned) and `integer`. - For `double` this picks the the closest `double` value to the integer ala - {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor]. - -Supported types: - -include::types/floor.asciidoc[] diff --git a/docs/reference/esql/functions/greatest.asciidoc b/docs/reference/esql/functions/greatest.asciidoc index 24dd08de2819c..b9fc114d39ec6 100644 --- a/docs/reference/esql/functions/greatest.asciidoc +++ b/docs/reference/esql/functions/greatest.asciidoc @@ -1,11 +1,34 @@ [discrete] [[esql-greatest]] === `GREATEST` + +*Syntax* + [.text-center] image::esql/functions/signature/greatest.svg[Embedded,opts=inline] -Returns the maximum value from many columns. This is similar to <> -except it's intended to run on multiple columns at once. +*Parameters* + +`first`:: +First of the columns to evaluate. + +`rest`:: +The rest of the columns to evaluate. + +*Description* + +Returns the maximum value from multiple columns. This is similar to <> +except it is intended to run on multiple columns at once. + +NOTE: When run on `keyword` or `text` fields, this returns the last string + in alphabetical order. When run on `boolean` columns this will return + `true` if any values are `true`. + +*Supported types* + +include::types/greatest.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,11 +38,3 @@ include::{esql-specs}/math.csv-spec[tag=greatest] |=== include::{esql-specs}/math.csv-spec[tag=greatest-result] |=== - -NOTE: When run on `keyword` or `text` fields, this'll return the last string - in alphabetical order. When run on `boolean` columns this will return - `true` if any values are `true`. - -Supported types: - -include::types/greatest.asciidoc[] diff --git a/docs/reference/esql/functions/least.asciidoc b/docs/reference/esql/functions/least.asciidoc index 62d7406199cd4..41f58b0d415c2 100644 --- a/docs/reference/esql/functions/least.asciidoc +++ b/docs/reference/esql/functions/least.asciidoc @@ -1,11 +1,34 @@ [discrete] [[esql-least]] === `LEAST` + +*Syntax* + [.text-center] image::esql/functions/signature/least.svg[Embedded,opts=inline] -Returns the minimum value from many columns. This is similar to <> -except it's intended to run on multiple columns at once. +*Parameters* + +`first`:: +First of the columns to evaluate. + +`rest`:: +The rest of the columns to evaluate. + +*Description* + +Returns the minimum value from multiple columns. This is similar to +<> except it is intended to run on multiple columns at once. + +NOTE: When run on `keyword` or `text` fields, this returns the first string + in alphabetical order. When run on `boolean` columns this will return + `false` if any values are `false`. + +*Supported types* + +include::types/least.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,11 +38,3 @@ include::{esql-specs}/math.csv-spec[tag=least] |=== include::{esql-specs}/math.csv-spec[tag=least-result] |=== - -NOTE: When run on `keyword` or `text` fields, this'll return the first string - in alphabetical order. When run on `boolean` columns this will return - `false` if any values are `false`. - -Supported types: - -include::types/least.asciidoc[] diff --git a/docs/reference/esql/functions/left.asciidoc b/docs/reference/esql/functions/left.asciidoc index 67e739377aa46..5d666656b1ee4 100644 --- a/docs/reference/esql/functions/left.asciidoc +++ b/docs/reference/esql/functions/left.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-left]] === `LEFT` + +*Syntax* + [.text-center] image::esql/functions/signature/left.svg[Embedded,opts=inline] -Return the substring that extracts 'length' chars from the 'string' starting from the left. +*Parameters* + +`str`:: +The string from which to return a substring. + +`length`:: +The number of characters to return. + +*Description* + +Returns the substring that extracts 'length' chars from 'str' starting +from the left. + +*Supported types* + +include::types/left.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=left] |=== include::{esql-specs}/string.csv-spec[tag=left-result] |=== - -Supported types: - -include::types/left.asciidoc[] diff --git a/docs/reference/esql/functions/length.asciidoc b/docs/reference/esql/functions/length.asciidoc index 12e1bed3d0a66..b89b75a702460 100644 --- a/docs/reference/esql/functions/length.asciidoc +++ b/docs/reference/esql/functions/length.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-length]] === `LENGTH` -Returns the character length of a string. + +*Syntax* [source,esql] ---- -FROM employees -| KEEP first_name, last_name, height -| EVAL fn_length = LENGTH(first_name) +LENGTH(str) +---- + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + +Returns the character length of a string. + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/eval.csv-spec[tag=length] ---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/eval.csv-spec[tag=length-result] +|=== diff --git a/docs/reference/esql/functions/log10.asciidoc b/docs/reference/esql/functions/log10.asciidoc index 219519ca2a0d7..d806da3173818 100644 --- a/docs/reference/esql/functions/log10.asciidoc +++ b/docs/reference/esql/functions/log10.asciidoc @@ -1,13 +1,27 @@ [discrete] [[esql-log10]] === `LOG10` + +*Syntax* + [.text-center] image::esql/functions/signature/log10.svg[Embedded,opts=inline] -Returns the log base 10. The input can be any numeric value, the return value -is always a double. +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* -Logs of negative numbers are NaN. Logs of infinites are infinite, as is the log of 0. +Returns the logarithm to base 10. The input can be any numeric value, the return +value is always a double. + +Logs of 0, negative numbers, and infinites return `null` as well as a warning. + +*Supported types* + +include::types/log10.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +31,3 @@ include::{esql-specs}/math.csv-spec[tag=log10] |=== include::{esql-specs}/math.csv-spec[tag=log10-result] |=== - -Supported types: - -include::types/log10.asciidoc[] diff --git a/docs/reference/esql/functions/ltrim.asciidoc b/docs/reference/esql/functions/ltrim.asciidoc index e5230e4edd41a..4b7b619d06afc 100644 --- a/docs/reference/esql/functions/ltrim.asciidoc +++ b/docs/reference/esql/functions/ltrim.asciidoc @@ -1,11 +1,27 @@ [discrete] [[esql-ltrim]] === `LTRIM` + +*Syntax* + [.text-center] image::esql/functions/signature/ltrim.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + Removes leading whitespaces from strings. +*Supported types* + +include::types/rtrim.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=ltrim] @@ -13,8 +29,4 @@ include::{esql-specs}/string.csv-spec[tag=ltrim] [%header.monospaced.styled,format=dsv,separator=|] |=== include::{esql-specs}/string.csv-spec[tag=ltrim-result] -|=== - -Supported types: - -include::types/rtrim.asciidoc[] +|=== \ No newline at end of file diff --git a/docs/reference/esql/functions/max.asciidoc b/docs/reference/esql/functions/max.asciidoc index 53997e501b37f..4bc62de341d9d 100644 --- a/docs/reference/esql/functions/max.asciidoc +++ b/docs/reference/esql/functions/max.asciidoc @@ -1,7 +1,24 @@ [discrete] [[esql-agg-max]] === `MAX` -The maximum value of a numeric field. + +*Syntax* + +[source,esql] +---- +MAX(column) +---- + +*Parameters* + +`column`:: +Column from which to return the maximum value. + +*Description* + +Returns the maximum value of a numeric column. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/median-absolute-deviation.asciidoc b/docs/reference/esql/functions/median-absolute-deviation.asciidoc index fe0923da1fb88..301d344489643 100644 --- a/docs/reference/esql/functions/median-absolute-deviation.asciidoc +++ b/docs/reference/esql/functions/median-absolute-deviation.asciidoc @@ -1,23 +1,29 @@ [discrete] [[esql-agg-median-absolute-deviation]] === `MEDIAN_ABSOLUTE_DEVIATION` -The median absolute deviation, a measure of variability. It is a robust -statistic, meaning that it is useful for describing data that may have outliers, -or may not be normally distributed. For such data it can be more descriptive than -standard deviation. -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) - Xi|)`. +*Syntax* -[source.merge.styled,esql] +[source,esql] ---- -include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation] +MEDIAN_ABSOLUTE_DEVIATION(column) ---- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation-result] -|=== + +*Parameters* + +`column`:: +Column from which to return the median absolute deviation. + +*Description* + +Returns the median absolute deviation, a measure of variability. It is a robust +statistic, meaning that it is useful for describing data that may have outliers, +or may not be normally distributed. For such data it can be more descriptive +than standard deviation. + +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|)`. NOTE: Like <>, `MEDIAN_ABSOLUTE_DEVIATION` is <>. @@ -27,3 +33,14 @@ NOTE: Like <>, `MEDIAN_ABSOLUTE_DEVIATION` is `MEDIAN_ABSOLUTE_DEVIATION` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic]. This means you can get slightly different results using the same data. ==== + +*Example* + +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation-result] +|=== diff --git a/docs/reference/esql/functions/median.asciidoc b/docs/reference/esql/functions/median.asciidoc index 5a0d0c049602e..17b51d9c50b26 100644 --- a/docs/reference/esql/functions/median.asciidoc +++ b/docs/reference/esql/functions/median.asciidoc @@ -1,17 +1,23 @@ [discrete] [[esql-agg-median]] === `MEDIAN` -The value that is greater than half of all values and less than half of -all values, also known as the 50% <>. -[source.merge.styled,esql] +*Syntax* + +[source,esql] ---- -include::{esql-specs}/stats_percentile.csv-spec[tag=median] +MEDIAN(column) ---- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/stats_percentile.csv-spec[tag=median-result] -|=== + +*Parameters* + +`column`:: +Column from which to return the median value. + +*Description* + +Returns the value that is greater than half of all values and less than half of +all values, also known as the 50% <>. NOTE: Like <>, `MEDIAN` is <>. @@ -20,3 +26,14 @@ NOTE: Like <>, `MEDIAN` is <> on them first: +To concat non-string columns, call <> first: [source.merge.styled,esql] ---- @@ -26,7 +45,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string] |=== include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string-result] |=== - -Supported types: - -include::types/mv_concat.asciidoc[] diff --git a/docs/reference/esql/functions/mv_count.asciidoc b/docs/reference/esql/functions/mv_count.asciidoc index e6a61cd6e9c63..0545335556030 100644 --- a/docs/reference/esql/functions/mv_count.asciidoc +++ b/docs/reference/esql/functions/mv_count.asciidoc @@ -1,11 +1,27 @@ [discrete] [[esql-mv_count]] === `MV_COUNT` + +*Syntax* + [.text-center] image::esql/functions/signature/mv_count.svg[Embedded,opts=inline] -Converts a multivalued field into a single valued field containing a count of the number -of values: +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing a count +of the number of values. + +*Supported types* + +include::types/mv_count.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,7 +31,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_count] |=== include::{esql-specs}/string.csv-spec[tag=mv_count-result] |=== - -Supported types: - -include::types/mv_count.asciidoc[] diff --git a/docs/reference/esql/functions/mv_dedupe.asciidoc b/docs/reference/esql/functions/mv_dedupe.asciidoc index c85c6ddff4354..09b3827c45e45 100644 --- a/docs/reference/esql/functions/mv_dedupe.asciidoc +++ b/docs/reference/esql/functions/mv_dedupe.asciidoc @@ -1,10 +1,28 @@ [discrete] [[esql-mv_dedupe]] === `MV_DEDUPE` + +*Syntax* + [.text-center] image::esql/functions/signature/mv_dedupe.svg[Embedded,opts=inline] -Removes duplicates from a multivalued field. For example: +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Removes duplicates from a multivalue expression. + +NOTE: `MV_DEDUPE` may, but won't always, sort the values in the column. + +*Supported types* + +include::types/mv_dedupe.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,9 +32,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_dedupe] |=== include::{esql-specs}/string.csv-spec[tag=mv_dedupe-result] |=== - -Supported types: - -include::types/mv_dedupe.asciidoc[] - -NOTE: `MV_DEDUPE` may, but won't always, sort the values in the field. diff --git a/docs/reference/esql/functions/mv_first.asciidoc b/docs/reference/esql/functions/mv_first.asciidoc index 42ac8930136cc..13d21b15f958e 100644 --- a/docs/reference/esql/functions/mv_first.asciidoc +++ b/docs/reference/esql/functions/mv_first.asciidoc @@ -1,11 +1,34 @@ [discrete] [[esql-mv_first]] === `MV_FIRST` + +*Syntax* + [.text-center] image::esql/functions/signature/mv_first.svg[Embedded,opts=inline] -Converts a multivalued field into a single valued field containing the first value. This is most -useful when reading from a function that emits multivalued fields in a known order like <>: +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +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 <>. + +The order that <> are read from +underlying storage is not guaranteed. It is *frequently* ascending, but don't +rely on that. If you need the minimum value use <> instead of +`MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn't a +performance benefit to `MV_FIRST`. + +*Supported types* + +include::types/mv_first.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,13 +38,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_first] |=== include::{esql-specs}/string.csv-spec[tag=mv_first-result] |=== - -The order that <> are read from underlying storage is not -guaranteed. It is *frequently* ascending, but don't rely on that. If you need the minimum field value -use <> instead of `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn't -a performance benefit to `MV_FIRST`. `MV_FIRST` is mostly useful with functions that create multivalued -fields like `SPLIT`. - -Supported types: - -include::types/mv_first.asciidoc[] diff --git a/docs/reference/esql/functions/mv_last.asciidoc b/docs/reference/esql/functions/mv_last.asciidoc index aa6fc40d0af07..ee6a4a8fed8ba 100644 --- a/docs/reference/esql/functions/mv_last.asciidoc +++ b/docs/reference/esql/functions/mv_last.asciidoc @@ -1,11 +1,34 @@ [discrete] [[esql-mv_last]] === `MV_LAST` + +*Syntax* + [.text-center] image::esql/functions/signature/mv_last.svg[Embedded,opts=inline] -Converts a multivalued field into a single valued field containing the last value. This is most -useful when reading from a function that emits multivalued fields in a known order like <>: +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +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 <>. + +The order that <> are read from +underlying storage is not guaranteed. It is *frequently* ascending, but don't +rely on that. If you need the maximum value use <> instead of +`MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't a +performance benefit to `MV_LAST`. + +*Supported types* + +include::types/mv_last.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,13 +38,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_last] |=== include::{esql-specs}/string.csv-spec[tag=mv_last-result] |=== - -The order that <> are read from underlying storage is not -guaranteed. It is *frequently* ascending, but don't rely on that. If you need the maximum field value -use <> instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't -a performance benefit to `MV_LAST`. `MV_LAST` is mostly useful with functions that create multivalued -fields like `SPLIT`. - -Supported types: - -include::types/mv_last.asciidoc[] diff --git a/docs/reference/esql/functions/mv_max.asciidoc b/docs/reference/esql/functions/mv_max.asciidoc index ed433b64a2813..e13e61e0d123d 100644 --- a/docs/reference/esql/functions/mv_max.asciidoc +++ b/docs/reference/esql/functions/mv_max.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-mv_max]] === `MV_MAX` + +*Syntax* + [.text-center] image::esql/functions/signature/mv_max.svg[Embedded,opts=inline] -Converts a multivalued field into a single valued field containing the maximum value. For example: +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing the +maximum value. + +*Supported types* + +include::types/mv_max.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -15,8 +32,8 @@ include::{esql-specs}/math.csv-spec[tag=mv_max] include::{esql-specs}/math.csv-spec[tag=mv_max-result] |=== -It can be used by any field type, including `keyword` fields. In that case picks the -last string, comparing their utf-8 representation byte by byte: +It can be used by any column type, including `keyword` columns. In that case +it picks the last string, comparing their utf-8 representation byte by byte: [source.merge.styled,esql] ---- @@ -26,7 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_max] |=== include::{esql-specs}/string.csv-spec[tag=mv_max-result] |=== - -Supported types: - -include::types/mv_max.asciidoc[] diff --git a/docs/reference/esql/functions/mv_median.asciidoc b/docs/reference/esql/functions/mv_median.asciidoc index c84cf7a895da5..05c54342c0f74 100644 --- a/docs/reference/esql/functions/mv_median.asciidoc +++ b/docs/reference/esql/functions/mv_median.asciidoc @@ -1,7 +1,27 @@ [discrete] [[esql-mv_median]] === `MV_MEDIAN` -Converts a multivalued field into a single valued field containing the median value. For example: + +[source,esql] +---- +MV_MEDIAN(v) +---- + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued column into a single valued column containing the median +value. + +*Supported types* + +include::types/mv_median.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -12,9 +32,9 @@ include::{esql-specs}/math.csv-spec[tag=mv_median] include::{esql-specs}/math.csv-spec[tag=mv_median-result] |=== -It can be used by any numeric field type and returns a value of the same type. If the -row has an even number of values for a column the result will be the average of the -middle two entries. If the field is not floating point then the average rounds *down*: +If the row has an even number of values for a column, the result will be the +average of the middle two entries. If the column is not floating point, the +average rounds *down*: [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/mv_min.asciidoc b/docs/reference/esql/functions/mv_min.asciidoc index b0c8dd51c97fc..b851f480fd619 100644 --- a/docs/reference/esql/functions/mv_min.asciidoc +++ b/docs/reference/esql/functions/mv_min.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-mv_min]] === `MV_MIN` + +*Syntax* + [.text-center] image::esql/functions/signature/mv_min.svg[Embedded,opts=inline] -Converts a multivalued field into a single valued field containing the minimum value. For example: +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued expression into a single valued column containing the +minimum value. + +*Supported types* + +include::types/mv_min.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -15,8 +32,8 @@ include::{esql-specs}/math.csv-spec[tag=mv_min] include::{esql-specs}/math.csv-spec[tag=mv_min-result] |=== -It can be used by any field type, including `keyword` fields. In that case picks the -first string, comparing their utf-8 representation byte by byte: +It can be used by any column type, including `keyword` columns. In that case, +it picks the first string, comparing their utf-8 representation byte by byte: [source.merge.styled,esql] ---- @@ -26,7 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_min] |=== include::{esql-specs}/string.csv-spec[tag=mv_min-result] |=== - -Supported types: - -include::types/mv_min.asciidoc[] diff --git a/docs/reference/esql/functions/mv_sum.asciidoc b/docs/reference/esql/functions/mv_sum.asciidoc index 646af03305954..bc252bc9d3fa0 100644 --- a/docs/reference/esql/functions/mv_sum.asciidoc +++ b/docs/reference/esql/functions/mv_sum.asciidoc @@ -1,8 +1,27 @@ [discrete] [[esql-mv_sum]] === `MV_SUM` -Converts a multivalued field into a single valued field containing the sum -of all of the values. For example: + +[source,esql] +---- +MV_SUM(v) +---- + +*Parameters* + +`v`:: +Multivalue expression. + +*Description* + +Converts a multivalued column into a single valued column containing the sum +of all of the values. + +*Supported types* + +include::types/mv_sum.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -12,5 +31,3 @@ include::{esql-specs}/math.csv-spec[tag=mv_sum] |=== include::{esql-specs}/math.csv-spec[tag=mv_sum-result] |=== - -NOTE: The input type can be any number and the output type is the same as the input type. diff --git a/docs/reference/esql/functions/now.asciidoc b/docs/reference/esql/functions/now.asciidoc index 5d33449a1e906..3c46f557acd1f 100644 --- a/docs/reference/esql/functions/now.asciidoc +++ b/docs/reference/esql/functions/now.asciidoc @@ -1,9 +1,28 @@ [discrete] [[esql-now]] === `NOW` + +*Syntax* + +[source,esql] +---- +NOW() +---- + +*Description* + Returns current date and time. +*Example* + [source,esql] ---- -ROW current_date = NOW() +include::{esql-specs}/date.csv-spec[tag=docsNow] +---- + +To retrieve logs from the last hour: + +[source,esql] ---- +include::{esql-specs}/date.csv-spec[tag=docsNowWhere] +---- \ No newline at end of file diff --git a/docs/reference/esql/functions/percentile.asciidoc b/docs/reference/esql/functions/percentile.asciidoc index 917a4a81e7b4f..ab3f14af70486 100644 --- a/docs/reference/esql/functions/percentile.asciidoc +++ b/docs/reference/esql/functions/percentile.asciidoc @@ -1,18 +1,27 @@ [discrete] [[esql-agg-percentile]] === `PERCENTILE` -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 <>. -[source.merge.styled,esql] +*Syntax* + +[source,esql] ---- -include::{esql-specs}/stats_percentile.csv-spec[tag=percentile] +PERCENTILE(column, percentile) ---- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/stats_percentile.csv-spec[tag=percentile-result] -|=== + +*Parameters* + +`column`:: +Column to convert from multiple values to single value. + +`percentile`:: +A constant numeric expression. + +*Description* + +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 <>. [discrete] [[esql-agg-percentile-approximate]] @@ -26,5 +35,13 @@ include::../../aggregations/metrics/percentile-aggregation.asciidoc[tag=approxim This means you can get slightly different results using the same data. ==== +*Example* - +[source.merge.styled,esql] +---- +include::{esql-specs}/stats_percentile.csv-spec[tag=percentile] +---- +[%header.monospaced.styled,format=dsv,separator=|] +|=== +include::{esql-specs}/stats_percentile.csv-spec[tag=percentile-result] +|=== diff --git a/docs/reference/esql/functions/pi.asciidoc b/docs/reference/esql/functions/pi.asciidoc index cd630aaabadcd..fb88cbffc99d0 100644 --- a/docs/reference/esql/functions/pi.asciidoc +++ b/docs/reference/esql/functions/pi.asciidoc @@ -1,10 +1,17 @@ [discrete] [[esql-pi]] === `PI` + +*Syntax* + [.text-center] image::esql/functions/signature/pi.svg[Embedded,opts=inline] -The {wikipedia}/Pi[ratio] of a circle's circumference to its diameter. +*Description* + +Returns the {wikipedia}/Pi[ratio] of a circle's circumference to its diameter. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/pow.asciidoc b/docs/reference/esql/functions/pow.asciidoc index b13151c8cbd76..8c31bd21e8a46 100644 --- a/docs/reference/esql/functions/pow.asciidoc +++ b/docs/reference/esql/functions/pow.asciidoc @@ -1,12 +1,31 @@ [discrete] [[esql-pow]] === `POW` + +*Syntax* + [.text-center] image::esql/functions/signature/pow.svg[Embedded,opts=inline] -Returns the value of a base (first argument) raised to the power of an exponent (second argument). -Both arguments must be numeric. The output is always a double. Note that it is still possible to overflow -a double result here; in that case, null will be returned. +*Parameters* + +`base`:: +Numeric expression. If `null`, the function returns `null`. + +`exponent`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +Returns the value of `base` raised to the power of `exponent`. Both arguments +must be numeric. The output is always a double. Note that it is still possible +to overflow a double result here; in that case, null will be returned. + +*Supported types* + +include::types/pow.asciidoc[] + +*Examples* [source.merge.styled,esql] ---- @@ -17,10 +36,6 @@ include::{esql-specs}/math.csv-spec[tag=powDI] include::{esql-specs}/math.csv-spec[tag=powDI-result] |=== - -[discrete] -==== Fractional exponents - The exponent can be a fraction, which is similar to performing a root. For example, the exponent of `0.5` will give the square root of the base: @@ -32,10 +47,3 @@ include::{esql-specs}/math.csv-spec[tag=powID-sqrt] |=== include::{esql-specs}/math.csv-spec[tag=powID-sqrt-result] |=== - -[discrete] -==== Table of supported input and output types - -For clarity, the following table describes the output result type for all combinations of numeric input types: - -include::types/pow.asciidoc[] diff --git a/docs/reference/esql/functions/replace.asciidoc b/docs/reference/esql/functions/replace.asciidoc index 9bc0f85fdddce..05856829eb193 100644 --- a/docs/reference/esql/functions/replace.asciidoc +++ b/docs/reference/esql/functions/replace.asciidoc @@ -1,11 +1,38 @@ [discrete] [[esql-replace]] === `REPLACE` -The function substitutes in the string (1st argument) any match of the regular expression (2nd argument) with the replacement string (3rd argument). -If any of the arguments are `NULL`, the result is `NULL`. +*Syntax* -. This example replaces an occurrence of the word "World" with the word "Universe": +[.text-center] +image::esql/functions/signature/replace.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. + +`regex`:: +Regular expression. + +`newStr`:: +Replacement string. + +*Description* + +The function substitutes in the string `str` any match of the regular expression +`regex` with the replacement string `newStr`. + +If any of the arguments is `null`, the result is `null`. + +*Supported types* + +include::types/replace.asciidoc[] + +*Example* + +This example replaces any occurrence of the word "World" with the word +"Universe": [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/right.asciidoc b/docs/reference/esql/functions/right.asciidoc index a0f18192d410d..1b291e53729ee 100644 --- a/docs/reference/esql/functions/right.asciidoc +++ b/docs/reference/esql/functions/right.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-right]] === `RIGHT` + +*Syntax* + [.text-center] image::esql/functions/signature/right.svg[Embedded,opts=inline] -Return the substring that extracts 'length' chars from the 'string' starting from the right. +*Parameters* + +`str`:: +The string from which to returns a substring. + +`length`:: +The number of characters to return. + +*Description* + +Return the substring that extracts 'length' chars from 'str' starting +from the right. + +*Supported types* + +include::types/right.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=right] |=== include::{esql-specs}/string.csv-spec[tag=right-result] |=== - -Supported types: - -include::types/right.asciidoc[] diff --git a/docs/reference/esql/functions/round.asciidoc b/docs/reference/esql/functions/round.asciidoc index 4ec71cf682d0f..7f1285e85f664 100644 --- a/docs/reference/esql/functions/round.asciidoc +++ b/docs/reference/esql/functions/round.asciidoc @@ -1,10 +1,31 @@ [discrete] [[esql-round]] === `ROUND` +*Syntax* + +[.text-center] +image::esql/functions/signature/round.svg[Embedded,opts=inline] + +*Parameters* + +`value`:: +Numeric expression. If `null`, the function returns `null`. + +`decimals`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + Rounds a number to the closest number with the specified number of digits. Defaults to 0 digits if no number of digits is provided. If the specified number of digits is negative, rounds to the number of digits left of the decimal point. +*Supported types* + +include::types/round.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/docs.csv-spec[tag=round] diff --git a/docs/reference/esql/functions/rtrim.asciidoc b/docs/reference/esql/functions/rtrim.asciidoc index 8eb0494e90d9e..588b7b9fc5433 100644 --- a/docs/reference/esql/functions/rtrim.asciidoc +++ b/docs/reference/esql/functions/rtrim.asciidoc @@ -1,11 +1,27 @@ [discrete] [[esql-rtrim]] === `RTRIM` + +*Syntax* + [.text-center] image::esql/functions/signature/rtrim.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + Removes trailing whitespaces from strings. +*Supported types* + +include::types/rtrim.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=rtrim] @@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=rtrim] |=== include::{esql-specs}/string.csv-spec[tag=rtrim-result] |=== - -Supported types: - -include::types/rtrim.asciidoc[] diff --git a/docs/reference/esql/functions/sin.asciidoc b/docs/reference/esql/functions/sin.asciidoc index d948bf2ec39a3..e6a8e0cf9331f 100644 --- a/docs/reference/esql/functions/sin.asciidoc +++ b/docs/reference/esql/functions/sin.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-sin]] === `SIN` + +*Syntax* + [.text-center] image::esql/functions/signature/sin.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Sine_and_cosine[Sine] trigonometric function. Input expected in radians. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Sine_and_cosine[Sine] trigonometric function. Input expected in +radians. + +*Supported types* + +include::types/sin.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=sin] |=== include::{esql-specs}/floats.csv-spec[tag=sin-result] |=== - -Supported types: - -include::types/sin.asciidoc[] diff --git a/docs/reference/esql/functions/sinh.asciidoc b/docs/reference/esql/functions/sinh.asciidoc index 11d1ea29bffef..683ae6962c2fd 100644 --- a/docs/reference/esql/functions/sinh.asciidoc +++ b/docs/reference/esql/functions/sinh.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-sinh]] === `SINH` + +*Syntax* + [.text-center] image::esql/functions/signature/sinh.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Hyperbolic_functions[Sine] hyperbolic function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Hyperbolic_functions[Sine] hyperbolic function. + +*Supported types* + +include::types/sinh.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=sinh] |=== include::{esql-specs}/floats.csv-spec[tag=sinh-result] |=== - -Supported types: - -include::types/sinh.asciidoc[] diff --git a/docs/reference/esql/functions/split.asciidoc b/docs/reference/esql/functions/split.asciidoc index a6f8869bf89ca..0a4ce584d01da 100644 --- a/docs/reference/esql/functions/split.asciidoc +++ b/docs/reference/esql/functions/split.asciidoc @@ -1,18 +1,33 @@ [discrete] [[esql-split]] === `SPLIT` -Split a single valued string into multiple strings. For example: -[source,esql] +[.text-center] +image::esql/functions/signature/split.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`delim`:: +Delimiter. Only single byte delimiters are currently supported. + +*Description* + +Splits a single valued string into multiple strings. + +*Supported types* + +include::types/split.asciidoc[] + +*Example* + +[source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=split] ---- - -Which splits `"foo;bar;baz;qux;quux;corge"` on `;` and returns an array: - -[%header,format=dsv,separator=|] +[%header.monospaced.styled,format=dsv,separator=|] |=== include::{esql-specs}/string.csv-spec[tag=split-result] |=== - -WARNING: Only single byte delimiters are currently supported. diff --git a/docs/reference/esql/functions/sqrt.asciidoc b/docs/reference/esql/functions/sqrt.asciidoc index 02f7060089971..faf504a6b0af4 100644 --- a/docs/reference/esql/functions/sqrt.asciidoc +++ b/docs/reference/esql/functions/sqrt.asciidoc @@ -1,13 +1,30 @@ [discrete] [[esql-sqrt]] === `SQRT` + +*Syntax* + [.text-center] image::esql/functions/signature/sqrt.svg[Embedded,opts=inline] -Returns the square root of a number. The input can be any numeric value, the return value -is always a double. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +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 are NaN. Square roots of infinites are +infinite. -Square roots of negative numbers are NaN. Square roots of infinites are infinite. +*Supported types* + +include::types/sqrt.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +34,3 @@ include::{esql-specs}/math.csv-spec[tag=sqrt] |=== include::{esql-specs}/math.csv-spec[tag=sqrt-result] |=== - -Supported types: - -include::types/sqrt.asciidoc[] diff --git a/docs/reference/esql/functions/starts_with.asciidoc b/docs/reference/esql/functions/starts_with.asciidoc index f98a76ef68206..4d45e89882400 100644 --- a/docs/reference/esql/functions/starts_with.asciidoc +++ b/docs/reference/esql/functions/starts_with.asciidoc @@ -1,11 +1,30 @@ [discrete] [[esql-starts_with]] === `STARTS_WITH` + +*Syntax* + [.text-center] image::esql/functions/signature/starts_with.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`prefix`:: +String expression. If `null`, the function returns `null`. + +*Description* + Returns a boolean that indicates whether a keyword string starts with another -string: +string. + +*Supported types* + +include::types/starts_with.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -15,7 +34,3 @@ include::{esql-specs}/docs.csv-spec[tag=startsWith] |=== include::{esql-specs}/docs.csv-spec[tag=startsWith-result] |=== - -Supported types: - -include::types/starts_with.asciidoc[] diff --git a/docs/reference/esql/functions/substring.asciidoc b/docs/reference/esql/functions/substring.asciidoc index 8b8234de05bba..73df7a19aa6b7 100644 --- a/docs/reference/esql/functions/substring.asciidoc +++ b/docs/reference/esql/functions/substring.asciidoc @@ -1,8 +1,36 @@ [discrete] [[esql-substring]] === `SUBSTRING` + +*Syntax* + +[.text-center] +image::esql/functions/signature/substring.svg[Embedded,opts=inline] + +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +`start`:: +Start position. + +`length`:: +Length of the substring from the start position. Optional; if omitted, all +positions after `start` are returned. + +*Description* + Returns a substring of a string, specified by a start position and an optional -length. This example returns the first three characters of every last name: +length. + +*Supported types* + +include::types/substring.asciidoc[] + +*Examples* + +This example returns the first three characters of every last name: [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/sum.asciidoc b/docs/reference/esql/functions/sum.asciidoc index abf790040114d..e88ebbeb3c771 100644 --- a/docs/reference/esql/functions/sum.asciidoc +++ b/docs/reference/esql/functions/sum.asciidoc @@ -1,7 +1,22 @@ [discrete] [[esql-agg-sum]] === `SUM` -The sum of a numeric field. + +*Syntax* + +[source,esql] +---- +SUM(column) +---- + +`column`:: +Numeric column. + +*Description* + +Returns the sum of a numeric column. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/tan.asciidoc b/docs/reference/esql/functions/tan.asciidoc index 03e450ff23b0e..cc06421616fc1 100644 --- a/docs/reference/esql/functions/tan.asciidoc +++ b/docs/reference/esql/functions/tan.asciidoc @@ -1,10 +1,27 @@ [discrete] [[esql-tan]] === `TAN` + +*Syntax* + [.text-center] image::esql/functions/signature/tan.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Sine_and_cosine[Tangent] trigonometric function. Input expected in radians. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Sine_and_cosine[Tangent] trigonometric function. Input expected in +radians. + +*Supported types* + +include::types/tan.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=tan] |=== include::{esql-specs}/floats.csv-spec[tag=tan-result] |=== - -Supported types: - -include::types/tan.asciidoc[] diff --git a/docs/reference/esql/functions/tanh.asciidoc b/docs/reference/esql/functions/tanh.asciidoc index 218a0155d861c..a21354d23ba50 100644 --- a/docs/reference/esql/functions/tanh.asciidoc +++ b/docs/reference/esql/functions/tanh.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-tanh]] === `TANH` + +*Syntax* + [.text-center] image::esql/functions/signature/tanh.svg[Embedded,opts=inline] -https://en.wikipedia.org/wiki/Hyperbolic_functions[Tangent] hyperbolic function. +*Parameters* + +`n`:: +Numeric expression. If `null`, the function returns `null`. + +*Description* + +{wikipedia}/Hyperbolic_functions[Tangent] hyperbolic function. + +*Supported types* + +include::types/tanh.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=tanh] |=== include::{esql-specs}/floats.csv-spec[tag=tanh-result] |=== - -Supported types: - -include::types/tanh.asciidoc[] diff --git a/docs/reference/esql/functions/tau.asciidoc b/docs/reference/esql/functions/tau.asciidoc index 61f352b0db8de..d9720eb34d795 100644 --- a/docs/reference/esql/functions/tau.asciidoc +++ b/docs/reference/esql/functions/tau.asciidoc @@ -1,10 +1,18 @@ [discrete] [[esql-tau]] === `TAU` + +*Syntax* + [.text-center] image::esql/functions/signature/tau.svg[Embedded,opts=inline] -The https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius. +*Description* + +Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference +to its radius. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/to_boolean.asciidoc b/docs/reference/esql/functions/to_boolean.asciidoc index 03f21a503218c..54c41625f3eba 100644 --- a/docs/reference/esql/functions/to_boolean.asciidoc +++ b/docs/reference/esql/functions/to_boolean.asciidoc @@ -1,14 +1,39 @@ [discrete] [[esql-to_boolean]] === `TO_BOOLEAN` -Converts an input value to a boolean value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a string or numeric type. +*Alias* + +`TO_BOOL` + +*Syntax* + +[source,esql] +---- +TO_BOOLEAN(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value to a boolean value. 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*. For example: +return *false*. + +The numerical value of *0* will be converted to *false*, anything else will be +converted to *true*. + +*Supported types* + +The input type must be of a string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -18,8 +43,3 @@ include::{esql-specs}/boolean.csv-spec[tag=to_boolean] |=== include::{esql-specs}/boolean.csv-spec[tag=to_boolean-result] |=== - -The numerical value of *0* will be converted to *false*, anything else will be -converted to *true*. - -Alias: TO_BOOL diff --git a/docs/reference/esql/functions/to_cartesianpoint.asciidoc b/docs/reference/esql/functions/to_cartesianpoint.asciidoc index a0e274bd1c5b2..223556d2c0e96 100644 --- a/docs/reference/esql/functions/to_cartesianpoint.asciidoc +++ b/docs/reference/esql/functions/to_cartesianpoint.asciidoc @@ -1,13 +1,31 @@ [discrete] [[esql-to_cartesianpoint]] === `TO_CARTESIANPOINT` -Converts an input value to a `point` value. -The input can be a single- or multi-valued field or an expression. -The input type must be a string or a cartesian `point`. +*Syntax* + +[source,esql] +---- +TO_CARTESIANPOINT(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value to a `point` value. A string will only be successfully converted if it respects the -https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format: +{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format. + +*Supported types* + +include::types/to_cartesianpoint.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +35,3 @@ include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str] |=== include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str-result] |=== - -Supported types: - -include::types/to_cartesianpoint.asciidoc[] diff --git a/docs/reference/esql/functions/to_cartesianshape.asciidoc b/docs/reference/esql/functions/to_cartesianshape.asciidoc index 6a19bdd3bacda..16aa275b7332b 100644 --- a/docs/reference/esql/functions/to_cartesianshape.asciidoc +++ b/docs/reference/esql/functions/to_cartesianshape.asciidoc @@ -1,13 +1,32 @@ [discrete] [[esql-to_cartesianshape]] === `TO_CARTESIANSHAPE` -Converts an input value to a `cartesian_shape` value. -The input can be a single- or multi-valued field or an expression. +*Syntax* + +[source,esql] +---- +TO_CARTESIANSHAPE(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. The input type must be a string or a `cartesian_shape`. +*Description* + +Converts an input value to a `cartesian_shape` value. + A string will only be successfully converted if it respects the -https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT] format: +{wikipedia}/Well-known_text_representation_of_geometry[WKT] format. + +*Supported types* + +include::types/to_cartesianshape.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +36,3 @@ include::{esql-specs}/spatial_shapes.csv-spec[tag=to_cartesianshape-str] |=== include::{esql-specs}/spatial_shapes.csv-spec[tag=to_cartesianshape-str-result] |=== - -Supported types: - -include::types/to_cartesianshape.asciidoc[] diff --git a/docs/reference/esql/functions/to_datetime.asciidoc b/docs/reference/esql/functions/to_datetime.asciidoc index 750c8025cb6c2..9baf7d818d93c 100644 --- a/docs/reference/esql/functions/to_datetime.asciidoc +++ b/docs/reference/esql/functions/to_datetime.asciidoc @@ -1,13 +1,36 @@ [discrete] [[esql-to_datetime]] === `TO_DATETIME` -Converts an input value to a date value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a string or numeric type. +*Alias* + +`TO_DT` + +*Syntax* + +[source,esql] +---- +TO_DATETIME(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +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 <>). For example: +`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. To convert dates in other formats, use +<>. + +*Supported types* + +The input type must be of a string or numeric type. + +*Examples* [source.merge.styled,esql] ---- @@ -30,10 +53,8 @@ A following header will contain the failure reason and the offending value: `"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"` - If the input parameter is of a numeric type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch]. -For example: +milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example: [source.merge.styled,esql] ---- @@ -43,5 +64,3 @@ include::{esql-specs}/date.csv-spec[tag=to_datetime-int] |=== include::{esql-specs}/date.csv-spec[tag=to_datetime-int-result] |=== - -Alias: TO_DT diff --git a/docs/reference/esql/functions/to_degrees.asciidoc b/docs/reference/esql/functions/to_degrees.asciidoc index 71b480253fe35..7b0846c9a4c3f 100644 --- a/docs/reference/esql/functions/to_degrees.asciidoc +++ b/docs/reference/esql/functions/to_degrees.asciidoc @@ -1,13 +1,29 @@ [discrete] [[esql-to_degrees]] === `TO_DEGREES` -Converts a number in https://en.wikipedia.org/wiki/Radian[radians] -to https://en.wikipedia.org/wiki/Degree_(angle)[degrees]. -The input can be a single- or multi-valued field or an expression. The input -type must be of a numeric type and result is always `double`. +*Syntax* -Example: +[source,esql] +---- +TO_DEGREES(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts a number in {wikipedia}/Radian[radians] to +{wikipedia}/Degree_(angle)[degrees]. + +*Supported types* + +The input type must be of a numeric type and result is always `double`. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/to_double.asciidoc b/docs/reference/esql/functions/to_double.asciidoc index 27ad84e4c7762..5d372d6c77c39 100644 --- a/docs/reference/esql/functions/to_double.asciidoc +++ b/docs/reference/esql/functions/to_double.asciidoc @@ -1,12 +1,37 @@ [discrete] [[esql-to_double]] === `TO_DOUBLE` + +*Alias* + +`TO_DBL` + +*Syntax* + +[source,esql] +---- +TO_DOUBLE(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to a double value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to double. -Example: +Boolean *true* will be converted to double *1.0*, *false* to *0.0*. + +*Supported types* + +The input type must be of a boolean, date, string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -17,22 +42,13 @@ include::{esql-specs}/floats.csv-spec[tag=to_double-str] include::{esql-specs}/floats.csv-spec[tag=to_double-str-result] |=== -Note that in this example, the last conversion of the string isn't -possible. When this happens, the result is a *null* value. In this case a -_Warning_ header is added to the response. The header will provide information -on the source of the failure: +Note that in this example, the last conversion of the string isn't possible. +When this happens, the result is a *null* value. In this case a _Warning_ header +is added to the response. The header will provide information on the source of +the failure: `"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."` A following header will contain the failure reason and the offending value: `"java.lang.NumberFormatException: For input string: \"foo\""` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to double. - -Boolean *true* will be converted to double *1.0*, *false* to *0.0*. - -Alias: TO_DBL diff --git a/docs/reference/esql/functions/to_geopoint.asciidoc b/docs/reference/esql/functions/to_geopoint.asciidoc index fc29ea7869ce7..d4d7d397d8f7b 100644 --- a/docs/reference/esql/functions/to_geopoint.asciidoc +++ b/docs/reference/esql/functions/to_geopoint.asciidoc @@ -1,13 +1,32 @@ [discrete] [[esql-to_geopoint]] === `TO_GEOPOINT` -Converts an input value to a `geo_point` value. -The input can be a single- or multi-valued field or an expression. +*Syntax* + +[source,esql] +---- +TO_GEOPOINT(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. The input type must be a string or a `geo_point`. +*Description* + +Converts an input value to a `geo_point` value. + +*Supported types* + +include::types/to_geopoint.asciidoc[] + A string will only be successfully converted if it respects the -https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format: +{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format. + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +36,3 @@ include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str] |=== include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str-result] |=== - -Supported types: - -include::types/to_geopoint.asciidoc[] diff --git a/docs/reference/esql/functions/to_geoshape.asciidoc b/docs/reference/esql/functions/to_geoshape.asciidoc index 8d489cce77fa5..7f87d1d46579c 100644 --- a/docs/reference/esql/functions/to_geoshape.asciidoc +++ b/docs/reference/esql/functions/to_geoshape.asciidoc @@ -1,13 +1,32 @@ [discrete] [[esql-to_geoshape]] === `TO_GEOSHAPE` -Converts an input value to a `geo_point` value. -The input can be a single- or multi-valued field or an expression. -The input type must be a string or a `geo_point`. +*Syntax* + +[source,esql] +---- +TO_GEOPOINT(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. +The input type must be a string or a `geo_shape`. + +*Description* + +Converts an input value to a `geo_shape` value. A string will only be successfully converted if it respects the -https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT] format: +{wikipedia}/Well-known_text_representation_of_geometry[WKT] format. + +*Supported types* + +include::types/to_geoshape.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -17,7 +36,3 @@ include::{esql-specs}/spatial_shapes.csv-spec[tag=to_geoshape-str] |=== include::{esql-specs}/spatial_shapes.csv-spec[tag=to_geoshape-str-result] |=== - -Supported types: - -include::types/to_geoshape.asciidoc[] diff --git a/docs/reference/esql/functions/to_integer.asciidoc b/docs/reference/esql/functions/to_integer.asciidoc index e62256930c5aa..f07bdcd231e40 100644 --- a/docs/reference/esql/functions/to_integer.asciidoc +++ b/docs/reference/esql/functions/to_integer.asciidoc @@ -1,12 +1,37 @@ [discrete] [[esql-to_integer]] === `TO_INTEGER` + +*Alias* + +`TO_INT` + +*Syntax* + +[source,esql] +---- +TO_INTEGER(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to an integer value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to integer. -Example: +Boolean *true* will be converted to integer *1*, *false* to *0*. + +*Supported types* + +The input type must be of a boolean, date, string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -27,12 +52,3 @@ provide information on the source of the failure: A following header will contain the failure reason and the offending value: `"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range"` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to integer. - -Boolean *true* will be converted to integer *1*, *false* to *0*. - -Alias: TO_INT diff --git a/docs/reference/esql/functions/to_ip.asciidoc b/docs/reference/esql/functions/to_ip.asciidoc index dea147eba1a41..28e98ea69c305 100644 --- a/docs/reference/esql/functions/to_ip.asciidoc +++ b/docs/reference/esql/functions/to_ip.asciidoc @@ -1,11 +1,24 @@ [discrete] [[esql-to_ip]] === `TO_IP` -Converts an input string to an IP value. -The input can be a single- or multi-valued field or an expression. +*Syntax* + +[source,esql] +---- +TO_IP(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input string to an IP value. -Example: +*Example* [source.merge.styled,esql] ---- @@ -16,10 +29,10 @@ include::{esql-specs}/ip.csv-spec[tag=to_ip] include::{esql-specs}/ip.csv-spec[tag=to_ip-result] |=== -Note that in the example above the last conversion of the string isn't -possible. When this happens, the result is a *null* value. In this case a -_Warning_ header is added to the response. The header will provide information -on the source of the failure: +Note that in this example, the last conversion of the string isn't possible. +When this happens, the result is a *null* value. In this case a _Warning_ header +is added to the response. The header will provide information on the source of +the failure: `"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."` diff --git a/docs/reference/esql/functions/to_long.asciidoc b/docs/reference/esql/functions/to_long.asciidoc index 9501c28a31657..04b2e3980a07d 100644 --- a/docs/reference/esql/functions/to_long.asciidoc +++ b/docs/reference/esql/functions/to_long.asciidoc @@ -1,12 +1,33 @@ [discrete] [[esql-to_long]] === `TO_LONG` + +*Syntax* + +[source,esql] +---- +TO_LONG(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to a long value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to long. + +Boolean *true* will be converted to long *1*, *false* to *0*. + +*Supported types* -Example: +The input type must be of a boolean, date, string or numeric type. + +*Example* [source.merge.styled,esql] ---- @@ -27,10 +48,3 @@ on the source of the failure: A following header will contain the failure reason and the offending value: `"java.lang.NumberFormatException: For input string: \"foo\""` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to long. - -Boolean *true* will be converted to long *1*, *false* to *0*. diff --git a/docs/reference/esql/functions/to_lower.asciidoc b/docs/reference/esql/functions/to_lower.asciidoc index 3d55e39e7c1ca..5b98d82c9a94f 100644 --- a/docs/reference/esql/functions/to_lower.asciidoc +++ b/docs/reference/esql/functions/to_lower.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-to_lower]] === `TO_LOWER` + +*Syntax* + [.text-center] image::esql/functions/signature/to_lower.svg[Embedded,opts=inline] -Returns a new string representing the input string converted to lower case +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + +Returns a new string representing the input string converted to lower case. + +*Supported types* + +include::types/to_lower.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=to_lower] |=== include::{esql-specs}/string.csv-spec[tag=to_lower-result] |=== - -Supported types: - -include::types/to_lower.asciidoc[] diff --git a/docs/reference/esql/functions/to_radians.asciidoc b/docs/reference/esql/functions/to_radians.asciidoc index 1f86f1fb983cc..f3b1fbd1f3794 100644 --- a/docs/reference/esql/functions/to_radians.asciidoc +++ b/docs/reference/esql/functions/to_radians.asciidoc @@ -1,13 +1,29 @@ [discrete] [[esql-to_radians]] === `TO_RADIANS` -Converts a number in https://en.wikipedia.org/wiki/Degree_(angle)[degrees] to -https://en.wikipedia.org/wiki/Radian[radians]. -The input can be a single- or multi-valued field or an expression. The input -type must be of a numeric type and result is always `double`. +*Syntax* -Example: +[source,esql] +---- +TO_RADIANS(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts a number in {wikipedia}/Degree_(angle)[degrees] to +{wikipedia}/Radian[radians]. + +*Supported types* + +The input type must be of a numeric type and result is always `double`. + +*Example* [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/to_string.asciidoc b/docs/reference/esql/functions/to_string.asciidoc index d03b6511b8de5..e771915977d97 100644 --- a/docs/reference/esql/functions/to_string.asciidoc +++ b/docs/reference/esql/functions/to_string.asciidoc @@ -1,10 +1,28 @@ [discrete] [[esql-to_string]] === `TO_STRING` + +*Alias* + +`TO_STR` + [.text-center] image::esql/functions/signature/to_string.svg[Embedded,opts=inline] -Converts a field into a string. For example: +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input value into a string. + +*Supported types* + +include::types/to_string.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -25,9 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=to_string_multivalue] |=== include::{esql-specs}/string.csv-spec[tag=to_string_multivalue-result] |=== - -Alias: TO_STR - -Supported types: - -include::types/to_string.asciidoc[] diff --git a/docs/reference/esql/functions/to_unsigned_long.asciidoc b/docs/reference/esql/functions/to_unsigned_long.asciidoc index af3ff05bf055c..a4a6cfd54ed6f 100644 --- a/docs/reference/esql/functions/to_unsigned_long.asciidoc +++ b/docs/reference/esql/functions/to_unsigned_long.asciidoc @@ -1,12 +1,38 @@ [discrete] [[esql-to_unsigned_long]] === `TO_UNSIGNED_LONG` + +*Aliases* + +`TO_ULONG`, `TO_UL` + +*Syntax* + +[source,esql] +---- +TO_UNSIGNED_LONG(v) +---- + +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + Converts an input value to an unsigned long value. -The input can be a single- or multi-valued field or an expression. The input -type must be of a boolean, date, string or numeric type. +*Supported types* -Example: +The input type must be of a boolean, date, string or numeric type. + +If the input parameter is of a date type, its value will be interpreted as +milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to unsigned +long. + +Boolean *true* will be converted to unsigned long *1*, *false* to *0*. + +*Example* [source.merge.styled,esql] ---- @@ -27,12 +53,3 @@ on the source of the failure: A following header will contain the failure reason and the offending value: `"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, nor \"e\" notation exponential mark."` - - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], -converted to unsigned long. - -Boolean *true* will be converted to unsigned long *1*, *false* to *0*. - -Alias: TO_ULONG, TO_UL diff --git a/docs/reference/esql/functions/to_upper.asciidoc b/docs/reference/esql/functions/to_upper.asciidoc index b451cc53d35e8..cea63bcbb4bb0 100644 --- a/docs/reference/esql/functions/to_upper.asciidoc +++ b/docs/reference/esql/functions/to_upper.asciidoc @@ -1,10 +1,26 @@ [discrete] [[esql-to_upper]] === `TO_UPPER` + +*Syntax* + [.text-center] image::esql/functions/signature/to_upper.svg[Embedded,opts=inline] -Returns a new string representing the input string converted to upper case +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + +Returns a new string representing the input string converted to upper case. + +*Supported types* + +include::types/to_upper.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=to_upper] |=== include::{esql-specs}/string.csv-spec[tag=to_upper-result] |=== - -Supported types: - -include::types/to_upper.asciidoc[] diff --git a/docs/reference/esql/functions/to_version.asciidoc b/docs/reference/esql/functions/to_version.asciidoc index 33419233c4788..6a1583889c87f 100644 --- a/docs/reference/esql/functions/to_version.asciidoc +++ b/docs/reference/esql/functions/to_version.asciidoc @@ -1,10 +1,30 @@ [discrete] [[esql-to_version]] === `TO_VERSION` + +*Alias* + +`TO_VER` + +*Syntax* + [.text-center] image::esql/functions/signature/to_version.svg[Embedded,opts=inline] -Converts an input string to a version value. For example: +*Parameters* + +`v`:: +Input value. The input can be a single- or multi-valued column or an expression. + +*Description* + +Converts an input string to a version value. + +*Supported types* + +include::types/to_version.asciidoc[] + +*Example* [source.merge.styled,esql] ---- @@ -14,11 +34,3 @@ include::{esql-specs}/version.csv-spec[tag=to_version] |=== include::{esql-specs}/version.csv-spec[tag=to_version-result] |=== - -The input can be a single- or multi-valued field or an expression. - -Alias: TO_VER - -Supported types: - -include::types/to_version.asciidoc[] diff --git a/docs/reference/esql/functions/trim.asciidoc b/docs/reference/esql/functions/trim.asciidoc index 6ace6118dd757..0b246b7526cd2 100644 --- a/docs/reference/esql/functions/trim.asciidoc +++ b/docs/reference/esql/functions/trim.asciidoc @@ -1,11 +1,27 @@ [discrete] [[esql-trim]] === `TRIM` + +*Syntax* + [.text-center] image::esql/functions/signature/trim.svg[Embedded,opts=inline] +*Parameters* + +`str`:: +String expression. If `null`, the function returns `null`. + +*Description* + Removes leading and trailing whitespaces from strings. +*Supported types* + +include::types/trim.asciidoc[] + +*Example* + [source.merge.styled,esql] ---- include::{esql-specs}/string.csv-spec[tag=trim] @@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=trim] |=== include::{esql-specs}/string.csv-spec[tag=trim-result] |=== - -Supported types: - -include::types/trim.asciidoc[] diff --git a/docs/reference/esql/processing-commands/where.asciidoc b/docs/reference/esql/processing-commands/where.asciidoc index 973b163b08b10..3076f92c40fc0 100644 --- a/docs/reference/esql/processing-commands/where.asciidoc +++ b/docs/reference/esql/processing-commands/where.asciidoc @@ -33,6 +33,14 @@ Which, if `still_hired` is a boolean field, can be simplified to: include::{esql-specs}/docs.csv-spec[tag=whereBoolean] ---- +Use date math to retrieve data from a specific time range. For example, to +retrieve the last hour of logs: + +[source,esql] +---- +include::{esql-specs}/date.csv-spec[tag=docsNowWhere] +---- + `WHERE` supports various <>. For example the <> function: 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 8dd9704fd2d4b..770e500024c34 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 @@ -1048,3 +1048,29 @@ hires:long | year:date 1 |1999-01-01T00:00:00.000Z // end::docsDateTruncHistogram-result[] ; + +docsNow +// tag::docsNow[] +ROW current_date = NOW() +// end::docsNow[] +| EVAL y = SUBSTRING(DATE_FORMAT("yyyy", current_date), 0, 2) +| KEEP y +; + +// tag::docsNow-result[] +y:keyword +20 +// end::docsNow-result[] +; + +docsNowWhere +// tag::docsNowWhere[] +FROM sample_data +| WHERE @timestamp > NOW() - 1 hour +// end::docsNowWhere[] +; + +// tag::docsNowWhere-result[] +@timestamp:date | client_ip:ip | event_duration:long | message:keyword +// end::docsNowWhere-result[] +; diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec index 7a7d2486d97e1..441f6d8a264fe 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec @@ -262,6 +262,24 @@ FROM sample_data @timestamp:date | client_ip:ip | event_duration:long | message:keyword | duration_ms:double ; +docsLength +// tag::length[] +FROM employees +| KEEP first_name, last_name +| EVAL fn_length = LENGTH(first_name) +// end::length[] +| SORT first_name +| LIMIT 3 +; + +// tag::length-result[] +first_name:keyword | last_name:keyword | fn_length:integer +Alejandro |McAlpine |9 +Amabile |Gomatam |7 +Anneke |Preusig |6 +// end::length-result[] +; + docsGettingStartedEvalNoColumnName // tag::gs-eval-no-column-name[] FROM sample_data