SQL: MATCH and QUERY documentation; one list of functions (#40494)

* Document MATCH and QUERY function predicates.
* Polish the functions pages and add a list of functions to the main Functions & Operators page.

docs/reference/sql/endpoints/jdbc.asciidoc

@@ -124,7 +124,8 @@ Query timeout (in seconds). That is the maximum amount of time waiting for a que
 
 [float]
 ==== Mapping
-`field.multi.value.leniency` (default `true`):: Whether to be lenient and return the first value for fields with multiple values (true) or throw an exception.
+`field.multi.value.leniency` (default `true`):: Whether to be lenient and return the first value (without any guarantees of what that
+will be - typically the first in natural ascending order) for fields with multiple values (true) or throw an exception.
 
 [float]
 ==== Additional

docs/reference/sql/functions/aggs.asciidoc

@@ -6,10 +6,12 @@
 Functions for computing a _single_ result from a set of input values.
 {es-sql} supports aggregate functions only alongside <<sql-syntax-group-by,grouping>> (implicit or explicit).
 
-==== General Purpose
+[[sql-functions-aggs-general]]
+[float]
+=== General Purpose
 
 [[sql-functions-aggs-avg]]
-===== `AVG`
+==== `AVG`
 
 .Synopsis:
 [source, sql]
@@ -33,7 +35,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggAvg]
 --------------------------------------------------
 
 [[sql-functions-aggs-count]]
-===== `COUNT`
+==== `COUNT`
 
 .Synopsis:
 [source, sql]
@@ -63,7 +65,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggCountStar]
 
 
 [[sql-functions-aggs-count-all]]
-===== `COUNT(ALL)`
+==== `COUNT(ALL)`
 
 .Synopsis:
 [source, sql]
@@ -88,7 +90,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggCountAll]
 
 
 [[sql-functions-aggs-count-distinct]]
-===== `COUNT(DISTINCT)`
+==== `COUNT(DISTINCT)`
 
 .Synopsis:
 [source, sql]
@@ -112,7 +114,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggCountDistinct]
 --------------------------------------------------
 
 [[sql-functions-aggs-first]]
-===== `FIRST/FIRST_VALUE`
+==== `FIRST/FIRST_VALUE`
 
 .Synopsis:
 [source, sql]
@@ -207,7 +209,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[firstValueWithTwoArgsAndGroupBy]
 the field is also <<before-enabling-fielddata,saved as a keyword>>.
 
 [[sql-functions-aggs-last]]
-===== `LAST/LAST_VALUE`
+==== `LAST/LAST_VALUE`
 
 .Synopsis:
 [source, sql]
@@ -302,7 +304,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[lastValueWithTwoArgsAndGroupBy]
 the field is also <<before-enabling-fielddata,`saved as a keyword`>>.
 
 [[sql-functions-aggs-max]]
-===== `MAX`
+==== `MAX`
 
 .Synopsis:
 [source, sql]
@@ -330,7 +332,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMax]
 <<sql-functions-aggs-last>> and therefore, it cannot be used in `HAVING` clause.
 
 [[sql-functions-aggs-min]]
-===== `MIN`
+==== `MIN`
 
 .Synopsis:
 [source, sql]
@@ -358,7 +360,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMin]
 <<sql-functions-aggs-first>> and therefore, it cannot be used in `HAVING` clause.
 
 [[sql-functions-aggs-sum]]
-===== `SUM`
+==== `SUM`
 
 .Synopsis:
 [source, sql]
@@ -381,10 +383,12 @@ Returns the sum of input values in the field `field_name`.
 include-tagged::{sql-specs}/docs/docs.csv-spec[aggSum]
 --------------------------------------------------
 
-==== Statistics
+[[sql-functions-aggs-statistics]]
+[float]
+=== Statistics
 
 [[sql-functions-aggs-kurtosis]]
-===== `KURTOSIS`
+==== `KURTOSIS`
 
 .Synopsis:
 [source, sql]
@@ -408,7 +412,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggKurtosis]
 --------------------------------------------------
 
 [[sql-functions-aggs-mad]]
-===== `MAD`
+==== `MAD`
 
 .Synopsis:
 [source, sql]
@@ -432,7 +436,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggMad]
 --------------------------------------------------
 
 [[sql-functions-aggs-percentile]]
-===== `PERCENTILE`
+==== `PERCENTILE`
 
 .Synopsis:
 [source, sql]
@@ -458,7 +462,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentile]
 --------------------------------------------------
 
 [[sql-functions-aggs-percentile-rank]]
-===== `PERCENTILE_RANK`
+==== `PERCENTILE_RANK`
 
 .Synopsis:
 [source, sql]
@@ -484,7 +488,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggPercentileRank]
 --------------------------------------------------
 
 [[sql-functions-aggs-skewness]]
-===== `SKEWNESS`
+==== `SKEWNESS`
 
 .Synopsis:
 [source, sql]
@@ -508,7 +512,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggSkewness]
 --------------------------------------------------
 
 [[sql-functions-aggs-stddev-pop]]
-===== `STDDEV_POP`
+==== `STDDEV_POP`
 
 .Synopsis:
 [source, sql]
@@ -532,7 +536,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggStddevPop]
 --------------------------------------------------
 
 [[sql-functions-aggs-sum-squares]]
-===== `SUM_OF_SQUARES`
+==== `SUM_OF_SQUARES`
 
 .Synopsis:
 [source, sql]
@@ -556,7 +560,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[aggSumOfSquares]
 --------------------------------------------------
 
 [[sql-functions-aggs-var-pop]]
-===== `VAR_POP`
+==== `VAR_POP`
 
 .Synopsis:
 [source, sql]

docs/reference/sql/functions/conditional.asciidoc

@@ -45,14 +45,13 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNonNull]
 include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNull]
 ----
 
-
-[[sql-functions-conditional-ifnull]]
-==== `IFNULL`
+[[sql-functions-conditional-greatest]]
+==== `GREATEST`
 
 .Synopsis:
 [source, sql]
 ----
-IFNULL(expression<1>, expression<2>)
+GREATEST(expression<1>, expression<2>, ...)
 ----
 
 *Input*:
@@ -61,35 +60,39 @@ IFNULL(expression<1>, expression<2>)
 
 <2> 2nd expression
 
+...
 
-*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
+**N**th expression
+
+GREATEST can take an arbitrary number of arguments and
+all of them must be of the same data type.
+
+*Output*: one of the expressions or `null`
 
 .Description
 
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
-Returns the first of its arguments that is not null.
+Returns the argument that has the largest value which is not null.
 If all arguments are null, then it returns `null`.
 
 
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[ifNullReturnFirst]
+include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNonNull]
 ----
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[ifNullReturnSecond]
+include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNull]
 ----
 
-
-[[sql-functions-conditional-isnull]]
-==== `ISNULL`
+[[sql-functions-conditional-ifnull]]
+==== `IFNULL`
 
 .Synopsis:
 [source, sql]
 ----
-ISNULL(expression<1>, expression<2>)
+IFNULL(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -111,22 +114,22 @@ If all arguments are null, then it returns `null`.
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnFirst]
+include-tagged::{sql-specs}/docs/docs.csv-spec[ifNullReturnFirst]
 ----
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnSecond]
+include-tagged::{sql-specs}/docs/docs.csv-spec[ifNullReturnSecond]
 ----
 
 
-[[sql-functions-conditional-nvl]]
-==== `NVL`
+[[sql-functions-conditional-isnull]]
+==== `ISNULL`
 
 .Synopsis:
 [source, sql]
 ----
-NVL(expression<1>, expression<2>)
+ISNULL(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -148,22 +151,22 @@ If all arguments are null, then it returns `null`.
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnFirst]
+include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnFirst]
 ----
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnSecond]
+include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnSecond]
 ----
 
 
-[[sql-functions-conditional-nullif]]
-==== `NULLIF`
+[[sql-functions-conditional-least]]
+==== `LEAST`
 
 .Synopsis:
 [source, sql]
 ----
-NULLIF(expression<1>, expression<2>)
+LEAST(expression<1>, expression<2>, ...)
 ----
 
 *Input*:
@@ -172,33 +175,40 @@ NULLIF(expression<1>, expression<2>)
 
 <2> 2nd expression
 
+...
 
-*Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
+**N**th expression
+
+LEAST can take an arbitrary number of arguments and
+all of them must be of the same data type.
+
+*Output*: one of the expressions or `null`
 
 .Description
 
-Returns `null` when the two input expressions are equal and
-if not, it returns the 1st expression.
+Returns the argument that has the smallest value which is not null.
+If all arguments are null, then it returns `null`.
+
 
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnFirst]
+include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNonNull]
 ----
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnNull]
+include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNull]
 ----
 
 
-[[sql-functions-conditional-greatest]]
-==== `GREATEST`
+[[sql-functions-conditional-nullif]]
+==== `NULLIF`
 
 .Synopsis:
 [source, sql]
 ----
-GREATEST(expression<1>, expression<2>, ...)
+NULLIF(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -207,40 +217,33 @@ GREATEST(expression<1>, expression<2>, ...)
 
 <2> 2nd expression
 
-...
-
-**N**th expression
-
-GREATEST can take an arbitrary number of arguments and
-all of them must be of the same data type.
 
-*Output*: one of the expressions or `null`
+*Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
 
 .Description
 
-Returns the argument that has the largest value which is not null.
-If all arguments are null, then it returns `null`.
-
+Returns `null` when the two input expressions are equal and
+if not, it returns the 1st expression.
 
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNonNull]
+include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnFirst]
 ----
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNull]
+include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnNull]
 ----
 
 
-[[sql-functions-conditional-least]]
-==== `LEAST`
+[[sql-functions-conditional-nvl]]
+==== `NVL`
 
 .Synopsis:
 [source, sql]
 ----
-LEAST(expression<1>, expression<2>, ...)
+NVL(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -249,28 +252,25 @@ LEAST(expression<1>, expression<2>, ...)
 
 <2> 2nd expression
 
-...
-
-**N**th expression
-
-LEAST can take an arbitrary number of arguments and
-all of them must be of the same data type.
 
-*Output*: one of the expressions or `null`
+*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
 .Description
 
-Returns the argument that has the smallest value which is not null.
+Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+Returns the first of its arguments that is not null.
 If all arguments are null, then it returns `null`.
 
 
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNonNull]
+include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnFirst]
 ----
 
 ["source","sql",subs="attributes,callouts,macros"]
 ----
-include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNull]
+include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnSecond]
 ----
+
+

docs/reference/sql/functions/index.asciidoc

@@ -7,14 +7,115 @@
 
 * <<sql-operators, Operators>>
 * <<sql-functions-aggs, Aggregate>>
+** <<sql-functions-aggs-avg, AVG>>
+** <<sql-functions-aggs-count, COUNT>>
+** <<sql-functions-aggs-count-all, COUNT(ALL)>>
+** <<sql-functions-aggs-count-distinct, COUNT(DISTINCT)>>
+** <<sql-functions-aggs-first, FIRST>>
+** <<sql-functions-aggs-last, LAST>>
+** <<sql-functions-aggs-max, MAX>>
+** <<sql-functions-aggs-min, MIN>>
+** <<sql-functions-aggs-sum, SUM>>
+** <<sql-functions-aggs-kurtosis, KURTOSIS>>
+** <<sql-functions-aggs-mad, MAD>>
+** <<sql-functions-aggs-percentile, PERCENTILE>>
+** <<sql-functions-aggs-percentile-rank, PERCENTILE_RANK>>
+** <<sql-functions-aggs-skewness, SKEWNESS>>
+** <<sql-functions-aggs-stddev-pop, STDDEV_POP>>
+** <<sql-functions-aggs-sum-squares, SUM_OF_SQUARES>>
+** <<sql-functions-aggs-var-pop, VAR_POP>>
 * <<sql-functions-grouping, Grouping>>
+** <<sql-functions-grouping-histogram, HISTOGRAM>>
 * <<sql-functions-datetime, Date-Time>>
+** <<sql-functions-datetime-interval, INTERVAL>>
+** <<sql-functions-current-date, CURRENT_DATE>>
+** <<sql-functions-current-timestamp, CURRENT_TIMESTAMP>>
+** <<sql-functions-datetime-day, DAY>>
+** <<sql-functions-datetime-dow, DAY_OF_WEEK>>
+** <<sql-functions-datetime-doy, DAY_OF_YEAR>>
+** <<sql-functions-datetime-dayname, DAY_NAME>>
+** <<sql-functions-datetime-hour, HOUR>>
+** <<sql-functions-datetime-isodow, ISO_DAY_OF_WEEK>>
+** <<sql-functions-datetime-isoweek, ISO_WEEK_OF_YEAR>>
+** <<sql-functions-datetime-minuteofday, MINUTE_OF_DAY>>
+** <<sql-functions-datetime-minute, MINUTE_OF_HOUR>>
+** <<sql-functions-datetime-month, MONTH_OF_YEAR>>
+** <<sql-functions-datetime-monthname, MONTH_NAME>>
+** <<sql-functions-now, NOW>>
+** <<sql-functions-datetime-second, SECOND_OF_MINUTE>>
+** <<sql-functions-datetime-quarter, QUARTER>>
+** <<sql-functions-today, TODAY>>
+** <<sql-functions-datetime-week, WEEK_OF_YEAR>>
+** <<sql-functions-datetime-year, YEAR>>
+** <<sql-functions-datetime-extract, EXTRACT>>
 * <<sql-functions-search, Full-Text Search>>
+** <<sql-functions-search-match, MATCH>>
+** <<sql-functions-search-query, QUERY>>
+** <<sql-functions-search-score, SCORE>>
 * <<sql-functions-math, Mathematical>>
+** <<sql-functions-math-abs, ABS>>
+** <<sql-functions-math-cbrt, CBRT>>
+** <<sql-functions-math-ceil, CEIL>>
+** <<sql-functions-math-e, E>>
+** <<sql-functions-math-exp, EXP>>
+** <<sql-functions-math-expm1, EXPM1>>
+** <<sql-functions-math-floor, FLOOR>>
+** <<sql-functions-math-log, LOG>>
+** <<sql-functions-math-log10, LOG10>>
+** <<sql-functions-math-pi, PI>>
+** <<sql-functions-math-power, POWER>>
+** <<sql-functions-math-random, RANDOM>> 
+** <<sql-functions-math-round, ROUND>>
+** <<sql-functions-math-sign, SIGN>>
+** <<sql-functions-math-sqrt, SQRT>>
+** <<sql-functions-math-truncate, TRUNCATE>>
+** <<sql-functions-math-acos, ACOS>>
+** <<sql-functions-math-asin, ASIN>>
+** <<sql-functions-math-atan, ATAN>>
+** <<sql-functions-math-atan2, ATAN2>>
+** <<sql-functions-math-cos, COS>>
+** <<sql-functions-math-cosh, COSH>>
+** <<sql-functions-math-cot, COT>>
+** <<sql-functions-math-degrees, DEGREES>>
+** <<sql-functions-math-radians, RADIANS>>
+** <<sql-functions-math-sin, SIN>>
+** <<sql-functions-math-sinh, SINH>>
+** <<sql-functions-math-tan, TAN>>
 * <<sql-functions-string, String>>
-* <<sql-functions-type-conversion,Type Conversion>>
+** <<sql-functions-string-ascii, ASCII>>
+** <<sql-functions-string-bit-length, BIT_LENGTH>>
+** <<sql-functions-string-char, CHAR>>
+** <<sql-functions-string-char-length, CHAR_LENGTH>>
+** <<sql-functions-string-concat, CONCAT>>
+** <<sql-functions-string-insert, INSERT>>
+** <<sql-functions-string-lcase, LCASE>>
+** <<sql-functions-string-left, LEFT>>
+** <<sql-functions-string-length, LENGTH>>
+** <<sql-functions-string-locate, LOCATE>>
+** <<sql-functions-string-ltrim, LTRIM>>
+** <<sql-functions-string-octet-length, OCTET_LENGTH>>
+** <<sql-functions-string-position, POSITION>>
+** <<sql-functions-string-repeat, REPEAT>>
+** <<sql-functions-string-replace, REPLACE>>
+** <<sql-functions-string-right, RIGHT>>
+** <<sql-functions-string-rtrim, RTRIM>>
+** <<sql-functions-string-space, SPACE>>
+** <<sql-functions-string-substring, SUBSTRING>>
+** <<sql-functions-string-ucase, UCASE>>
+* <<sql-functions-type-conversion, Type Conversion>>
+** <<sql-functions-type-conversion-cast, CAST>>
+** <<sql-functions-type-conversion-convert, CONVERT>>
 * <<sql-functions-conditional, Conditional>>
+** <<sql-functions-conditional-coalesce, COALESCE>>
+** <<sql-functions-conditional-greatest, GREATEST>>
+** <<sql-functions-conditional-ifnull, IFNULL>>
+** <<sql-functions-conditional-isnull, ISNULL>>
+** <<sql-functions-conditional-least, LEAST>>
+** <<sql-functions-conditional-nullif, NULLIF>>
+** <<sql-functions-conditional-nvl, NVL>>
 * <<sql-functions-system, System>>
+** <<sql-functions-system-database, DATABASE>>
+** <<sql-functions-system-user, USER>>
 
 include::operators.asciidoc[]
 include::aggs.asciidoc[]

docs/reference/sql/functions/math.asciidoc

@@ -6,10 +6,12 @@
 All math and trigonometric functions require their input (where applicable)
 to be numeric.
 
-==== Generic
+[[sql-functions-math-generic]]
+[float]
+=== Generic
 
 [[sql-functions-math-abs]]
-===== `ABS`
+==== `ABS`
 
 .Synopsis:
 [source, sql]
@@ -33,7 +35,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[abs]
 --------------------------------------------------
 
 [[sql-functions-math-cbrt]]
-===== `CBRT`
+==== `CBRT`
 
 .Synopsis:
 [source, sql]
@@ -57,7 +59,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCbrtWithNegativeValue]
 --------------------------------------------------
 
 [[sql-functions-math-ceil]]
-===== `CEIL/CEILING`
+==== `CEIL/CEILING`
 
 .Synopsis:
 [source, sql]
@@ -81,7 +83,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCeiling]
 --------------------------------------------------
 
 [[sql-functions-math-e]]
-===== `E`
+==== `E`
 
 .Synopsis:
 [source, sql]
@@ -103,7 +105,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathEulersNumber]
 --------------------------------------------------
 
 [[sql-functions-math-exp]]
-===== `EXP`
+==== `EXP`
 
 .Synopsis:
 [source, sql]
@@ -127,7 +129,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathExpInline]
 --------------------------------------------------
 
 [[sql-functions-math-expm1]]
-===== `EXPM1`
+==== `EXPM1`
 
 .Synopsis:
 [source, sql]
@@ -151,7 +153,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathExpm1Inline]
 --------------------------------------------------
 
 [[sql-functions-math-floor]]
-===== `FLOOR`
+==== `FLOOR`
 
 .Synopsis:
 [source, sql]
@@ -175,7 +177,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineFloor]
 --------------------------------------------------
 
 [[sql-functions-math-log]]
-===== `LOG`
+==== `LOG`
 
 .Synopsis:
 [source, sql]
@@ -199,7 +201,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineLog]
 --------------------------------------------------
 
 [[sql-functions-math-log10]]
-===== `LOG10`
+==== `LOG10`
 
 .Synopsis:
 [source, sql]
@@ -223,7 +225,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineLog10]
 --------------------------------------------------
 
 [[sql-functions-math-pi]]
-===== `PI`
+==== `PI`
 
 .Synopsis:
 [source, sql]
@@ -245,7 +247,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathPINumber]
 --------------------------------------------------
 
 [[sql-functions-math-power]]
-===== `POWER`
+==== `POWER`
 
 .Synopsis:
 [source, sql]
@@ -275,7 +277,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlinePowerNegative]
 --------------------------------------------------
 
 [[sql-functions-math-random]]
-===== `RANDOM/RAND`
+==== `RANDOM/RAND`
 
 .Synopsis:
 [source, sql]
@@ -299,7 +301,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathRandom]
 --------------------------------------------------
 
 [[sql-functions-math-round]]
-===== `ROUND`
+==== `ROUND`
 
 .Synopsis:
 [source, sql]
@@ -330,7 +332,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathRoundWithNegativeParameter]
 --------------------------------------------------
 
 [[sql-functions-math-sign]]
-===== `SIGN/SIGNUM`
+==== `SIGN/SIGNUM`
 
 .Synopsis:
 [source, sql]
@@ -355,7 +357,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSign]
 
 
 [[sql-functions-math-sqrt]]
-===== `SQRT`
+==== `SQRT`
 
 .Synopsis:
 [source, sql]
@@ -379,7 +381,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSqrt]
 --------------------------------------------------
 
 [[sql-functions-math-truncate]]
-===== `TRUNCATE`
+==== `TRUNCATE`
 
 .Synopsis:
 [source, sql]
@@ -409,10 +411,12 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathTruncateWithPositiveParameter
 include-tagged::{sql-specs}/docs/docs.csv-spec[mathTruncateWithNegativeParameter]
 --------------------------------------------------
 
-==== Trigonometric
+[[sql-functions-math-trigonometric]]
+[float]
+=== Trigonometric
 
 [[sql-functions-math-acos]]
-===== `ACOS`
+==== `ACOS`
 
 .Synopsis:
 [source, sql]
@@ -436,7 +440,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAcos]
 --------------------------------------------------
 
 [[sql-functions-math-asin]]
-===== `ASIN`
+==== `ASIN`
 
 .Synopsis:
 [source, sql]
@@ -460,7 +464,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAsin]
 --------------------------------------------------
 
 [[sql-functions-math-atan]]
-===== `ATAN`
+==== `ATAN`
 
 .Synopsis:
 [source, sql]
@@ -484,7 +488,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAtan]
 --------------------------------------------------
 
 [[sql-functions-math-atan2]]
-===== `ATAN2`
+==== `ATAN2`
 
 .Synopsis:
 [source, sql]
@@ -509,7 +513,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineAtan2]
 --------------------------------------------------
 
 [[sql-functions-math-cos]]
-===== `COS`
+==== `COS`
 
 .Synopsis:
 [source, sql]
@@ -533,7 +537,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCosine]
 --------------------------------------------------
 
 [[sql-functions-math-cosh]]
-===== `COSH`
+==== `COSH`
 
 .Synopsis:
 [source, sql]
@@ -557,7 +561,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCosh]
 --------------------------------------------------
 
 [[sql-functions-math-cot]]
-===== `COT`
+==== `COT`
 
 .Synopsis:
 [source, sql]
@@ -581,7 +585,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineCotangent]
 --------------------------------------------------
 
 [[sql-functions-math-degrees]]
-===== `DEGREES`
+==== `DEGREES`
 
 .Synopsis:
 [source, sql]
@@ -606,7 +610,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineDegrees]
 --------------------------------------------------
 
 [[sql-functions-math-radians]]
-===== `RADIANS`
+==== `RADIANS`
 
 .Synopsis:
 [source, sql]
@@ -631,7 +635,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineRadians]
 --------------------------------------------------
 
 [[sql-functions-math-sin]]
-===== `SIN`
+==== `SIN`
 
 .Synopsis:
 [source, sql]
@@ -655,7 +659,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSine]
 --------------------------------------------------
 
 [[sql-functions-math-sinh]]
-===== `SINH`
+==== `SINH`
 
 .Synopsis:
 [source, sql]
@@ -679,7 +683,7 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[mathInlineSinh]
 --------------------------------------------------
 
 [[sql-functions-math-tan]]
-===== `TAN`
+==== `TAN`
 
 .Synopsis:
 [source, sql]

docs/reference/sql/functions/search.asciidoc

@@ -8,6 +8,118 @@ when the `MATCH` or `QUERY` predicates are being used.
 Outside a, so-called, search context, these functions will return default values
 such as `0` or `NULL`.
 
+[[sql-functions-search-match]]
+==== `MATCH`
+
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+MATCH(field_exp<1>, constant_exp<2>[, options]<3>)
+--------------------------------------------------
+
+*Input*:
+
+<1> field(s) to match
+<2> matching text
+<3> additional parameters; optional
+
+.Description:
+
+A full-text search option, in the form of a predicate, available in {es-sql} that gives the user control over powerful <<query-dsl-match-query,match>>
+and <<query-dsl-multi-match-query,multi_match>> {es} queries.
+
+The first parameter is the field or fields to match against. In case it receives one value only, {es-sql} will use a `match` query to perform the search:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[simpleMatch]
+----
+
+However, it can also receive a list of fields and their corresponding optional `boost` value. In this case, {es-sql} will use a
+`multi_match` query to match the documents:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[multiFieldsMatch]
+----
+
+NOTE: The `multi_match` query in {es} has the option of <<query-dsl-multi-match-query,per-field boosting>> that gives preferential weight
+(in terms of scoring) to fields being searched in, using the `^` character. In the example above, the `name` field has a greater weight in
+the final score than the `author` field when searching for `frank dune` text in both of them.
+
+Both options above can be used in combination with the optional third parameter of the `MATCH()` predicate, where one can specify
+additional configuration parameters (separated by semicolon `;`) for either `match` or `multi_match` queries. For example:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[optionalParamsForMatch]
+----
+
+In the more advanced example above, the `cutoff_frequency` parameter allows specifying an absolute or relative document frequency where
+high frequency terms are moved into an optional subquery and are only scored if one of the low frequency (below the cutoff) terms in the 
+case of an `or` operator or all of the low frequency terms in the case of an `and` operator match. More about this you can find in the
+<<query-dsl-match-query-cutoff>> page.
+
+NOTE: The allowed optional parameters for a single-field `MATCH()` variant (for the `match` {es} query) are: `analyzer`, `auto_generate_synonyms_phrase_query`,
+`cutoff_frequency`, `lenient`, `fuzzy_transpositions`, `fuzzy_rewrite`, `minimum_should_match`, `operator`,
+`max_expansions`, `prefix_length`.
+
+NOTE: The allowed optional parameters for a multi-field `MATCH()` variant (for the `multi_match` {es} query) are: `analyzer`, `auto_generate_synonyms_phrase_query`,
+`cutoff_frequency`, `lenient`, `fuzzy_transpositions`, `fuzzy_rewrite`, `minimum_should_match`, `operator`,
+`max_expansions`, `prefix_length`, `slop`, `tie_breaker`, `type`.
+
+
+[[sql-functions-search-query]]
+==== `QUERY`
+
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+QUERY(constant_exp<1>[, options]<2>)
+--------------------------------------------------
+
+*Input*:
+
+<1> query text
+<2> additional parameters; optional
+
+.Description:
+
+Just like `MATCH`, `QUERY` is a full-text search predicate that gives the user control over the <<query-dsl-query-string-query,query_string>> query in {es}.
+
+The first parameter is basically the input that will be passed as is to the `query_string` query, which means that anything that `query_string`
+accepts in its `query` field can be used here as well:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[simpleQueryQuery]
+----
+
+A more advanced example, showing more of the features that `query_string` supports, of course possible with {es-sql}:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[advancedQueryQuery]
+----
+
+The query above uses the `_exists_` query to select documents that have values in the `author` field, a range query for `page_count` and
+regex and fuzziness queries for the `name` field.
+
+If one needs to customize various configuration options that `query_string` exposes, this can be done using the second _optional_ parameter.
+Multiple settings can be specified separated by a semicolon `;`:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[optionalParameterQuery]
+----
+
+NOTE: The allowed optional parameters for `QUERY()` are: `allow_leading_wildcard`, `analyze_wildcard`, `analyzer`,
+`auto_generate_synonyms_phrase_query`, `default_field`, `default_operator`, `enable_position_increments`,
+`escape`, `fuzzy_max_expansions`, `fuzzy_prefix_length`, `fuzzy_rewrite`, `fuzzy_transpositions`, `lenient`,
+`locale`, `lowercase_expanded_terms`, `max_determinized_states`, `minimum_should_match`, `phrase_slop`, `rewrite`,
+`quote_analyzer`, `quote_field_suffix`, `tie_breaker`, `time_zone`, `type`.
+
+
 [[sql-functions-search-score]]
 ==== `SCORE`
 

docs/reference/sql/language/syntax/commands/select.asciidoc

@@ -71,7 +71,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[wildcardWithOrder]
 which essentially returns all(top-level fields, sub-fields, such as multi-fields are ignored] columns found.
 
 [[sql-syntax-from]]
-[float]
 ==== FROM Clause
 
 The `FROM` clause specifies one table for the `SELECT` and has the following syntax:
@@ -111,7 +110,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[fromTableAlias]
 ----
 
 [[sql-syntax-where]]
-[float]
 ==== WHERE Clause
 
 The optional `WHERE` clause is used to filter rows from the query and has the following syntax:
@@ -133,7 +131,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[basicWhere]
 ----
 
 [[sql-syntax-group-by]]
-[float]
 ==== GROUP BY
 
 The `GROUP BY` clause is used to divide the results into groups of rows on matching values from the designated columns. It has the following syntax:
@@ -208,7 +205,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByAndMultipleAggs]
 ----
 
 [[sql-syntax-group-by-implicit]]
-[float]
 ===== Implicit Grouping
 
 When an aggregation is used without an associated `GROUP BY`, an __implicit grouping__ is applied, meaning all selected rows are considered to form a single default, or implicit group.
@@ -229,7 +225,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByImplicitMultipleAggs]
 ----
 
 [[sql-syntax-having]]
-[float]
 ==== HAVING
 
 The `HAVING` clause can be used _only_ along aggregate functions (and thus `GROUP BY`) to filter what groups are kept or not and has the following syntax:
@@ -263,7 +258,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByHavingMultiple]
 ----
 
 [[sql-syntax-having-group-by-implicit]]
-[float]
 ===== Implicit Grouping
 
 As indicated above, it is possible to have a `HAVING` clause without a `GROUP BY`. In this case, the so-called <<sql-syntax-group-by-implicit, __implicit grouping__>> is applied, meaning all selected rows are considered to form a single group and `HAVING` can be applied on any of the aggregate functions specified on this group.
@@ -285,7 +279,6 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[groupByHavingImplicitMatch]
 
 
 [[sql-syntax-order-by]]
-[float]
 ==== ORDER BY
 
 The `ORDER BY` clause is used to sort the results of `SELECT` by one or more expressions:
@@ -373,7 +366,6 @@ Trying to return `score` from a non full-text query will return the same value f
 all are equally relevant.
 
 [[sql-syntax-limit]]
-[float]
 ==== LIMIT
 
 The `LIMIT` clause restricts (limits) the number of rows returns using the format:

x-pack/plugin/sql/qa/src/main/resources/docs/docs.csv-spec

@@ -929,6 +929,84 @@ null           |25324
 // end::orderByAgg
 ;
 
+simpleMatch
+// tag::simpleMatch
+SELECT author, name FROM library WHERE MATCH(author, 'frank');
+
+    author     |       name
+---------------+-------------------
+Frank Herbert  |Dune
+Frank Herbert  |Dune Messiah
+Frank Herbert  |Children of Dune
+Frank Herbert  |God Emperor of Dune
+
+// end::simpleMatch
+;
+
+multiFieldsMatch
+// tag::multiFieldsMatch
+SELECT author, name, SCORE() FROM library WHERE MATCH('author^2,name^5', 'frank dune');
+
+    author     |       name        |    SCORE()
+---------------+-------------------+---------------
+Frank Herbert  |Dune               |11.443176
+Frank Herbert  |Dune Messiah       |9.446629
+Frank Herbert  |Children of Dune   |8.043278
+Frank Herbert  |God Emperor of Dune|7.0029488
+
+// end::multiFieldsMatch
+;
+
+optionalParamsForMatch
+// tag::optionalParamsForMatch
+SELECT author, name, SCORE() FROM library WHERE MATCH(name, 'to the star', 'operator=or;cutoff_frequency=0.2');
+
+     author      |                name                |    SCORE()
+-----------------+------------------------------------+---------------
+Peter F. Hamilton|Pandora's Star                      |3.0997515
+Douglas Adams    |The Hitchhiker's Guide to the Galaxy|3.1756816
+
+// end::optionalParamsForMatch
+;
+
+simpleQueryQuery
+// tag::simpleQueryQuery
+SELECT author, name, SCORE() FROM library WHERE QUERY('name:dune');
+
+    author     |       name        |    SCORE()
+---------------+-------------------+---------------
+Frank Herbert  |Dune               |2.2886353
+Frank Herbert  |Dune Messiah       |1.8893257
+Frank Herbert  |Children of Dune   |1.6086556
+Frank Herbert  |God Emperor of Dune|1.4005898
+// end::simpleQueryQuery
+;
+
+advancedQueryQuery
+// tag::advancedQueryQuery
+SELECT author, name, page_count, SCORE() FROM library WHERE QUERY('_exists_:"author" AND page_count:>200 AND (name:/star.*/ OR name:duna~)');
+
+      author      |       name        |  page_count   |    SCORE()
+------------------+-------------------+---------------+---------------
+Frank Herbert     |Dune               |604            |3.7164764
+Frank Herbert     |Dune Messiah       |331            |3.4169943
+Frank Herbert     |Children of Dune   |408            |3.2064917
+Frank Herbert     |God Emperor of Dune|454            |3.0504425
+Peter F. Hamilton |Pandora's Star     |768            |3.0
+Robert A. Heinlein|Starship Troopers  |335            |3.0
+// end::advancedQueryQuery
+;
+
+optionalParameterQuery
+// tag::optionalParameterQuery
+SELECT author, name, SCORE() FROM library WHERE QUERY('dune god', 'default_operator=and;default_field=name');
+
+    author     |       name        |    SCORE()
+---------------+-------------------+---------------
+Frank Herbert  |God Emperor of Dune|3.6984892
+// end::optionalParameterQuery
+;
+
 orderByScore
 // tag::orderByScore
 SELECT SCORE(), * FROM library WHERE MATCH(name, 'dune') ORDER BY SCORE() DESC;