SQL: documentation improvements and updates (#36918)

* Added Limitations page
* Made the aggregations page follow the common template for functions
* Modified all tables to have the first row's cells content centered
* Polishing in other various sections

docs/reference/sql/appendix/syntax-reserved.asciidoc

@@ -16,11 +16,13 @@ be quoted (using double quotes) in order to be used as an identifier, for exampl
 SELECT "AS" FROM index
 ----
 
-[cols="^,^,^",options="header"]
+[cols="^,^,^"]
 
 |===
 
-|Keyword                      |SQL:2016      |SQL-92
+s|Keyword
+s|SQL:2016
+s|SQL-92
 
 
 |`ALL`                        |reserved      |reserved

docs/reference/sql/concepts.asciidoc

@@ -15,6 +15,8 @@ Last but not least, {es-sql} tries to obey the https://en.wikipedia.org/wiki/Pri
 
 === Mapping concepts across SQL and {es}
 
+beta[]
+
 While SQL and {es} have different terms for the way the data is organized (and different semantics), essentially their purpose is the same.
 
 So let's start from the bottom; these roughly are:

docs/reference/sql/endpoints/client-apps/squirrel.asciidoc

@@ -1,13 +1,13 @@
 [role="xpack"]
 [testenv="platinum"]
 [[sql-client-apps-squirrel]]
-=== SQquirelL SQL
+=== SQuirreL SQL
 
 beta[]
 
 [quote, http://squirrel-sql.sourceforge.net/]
 ____
-http://squirrel-sql.sourceforge.net/[SQuirelL SQL] is a graphical, [multi-platform] Java program that will allow you to view the structure of a JDBC compliant database [...].
+http://squirrel-sql.sourceforge.net/[SQuirreL SQL] is a graphical, [multi-platform] Java program that will allow you to view the structure of a JDBC compliant database [...].
 ____
 
 ==== Prerequisites

docs/reference/sql/endpoints/jdbc.asciidoc

@@ -138,6 +138,8 @@ Opens up a {es-sql} connection to `server` on port `3456`, setting the JDBC conn
 
 === API usage
 
+beta[]
+
 One can use JDBC through the official `java.sql` and `javax.sql` packages:
 
 ==== `java.sql`

docs/reference/sql/functions/aggs.asciidoc

@@ -13,158 +13,317 @@ Functions for computing a _single_ result from a set of input values.
 [[sql-functions-aggs-avg]]
 ===== `AVG`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+AVG(numeric_field<1>)
+--------------------------------------------------
 
-https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
+*Input*:
 
+<1> numeric field
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+*Output*: `double` numeric value
+
+.Description:
+
+Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggAvg]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-count]]
 ===== `COUNT`
 
-*Input*: Any, *Output*: `bigint`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+COUNT(expression<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a field name, wildcard (`*`) or any numeric value
+
+*Output*: numeric value
+
+.Description:
 
-Total number (count) of input values.
+Returns the total number (count) of input values.
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggCountStar]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-count-distinct]]
 ===== `COUNT(DISTINCT)`
 
-*Input*: Any, *Output*: `bigint`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+COUNT(DISTINCT field_name<1>)
+--------------------------------------------------
 
-Total number of _distinct_ values in input values.
+*Input*:
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+<1> a field name
+
+*Output*: numeric value
+
+.Description:
+
+Returns the total number of _distinct_ values in input values.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggCountDistinct]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-max]]
 ===== `MAX`
 
-*Input*: Numeric, *Output*: Same as input
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+MAX(field_name<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
 
-Maximum value across input values.
+*Output*: same type as the input
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+.Description:
+
+Returns the maximum value across input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggMax]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-min]]
 ===== `MIN`
 
-*Input*: Numeric, *Output*: Same as input
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+MIN(field_name<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
 
-Minimum value across input values.
+*Output*: same type as the input
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+.Description:
+
+Returns the minimum value across input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggMin]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-sum]]
 ===== `SUM`
 
-*Input*: Numeric, *Output*: `bigint` for integer input, `double` for floating points
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+SUM(field_name<1>)
+--------------------------------------------------
+
+*Input*:
 
-Sum of input values.
+<1> a numeric field
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+*Output*: `bigint` for integer input, `double` for floating points
+
+.Description:
+
+Returns the sum of input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggSum]
-----
+--------------------------------------------------
 
 ==== Statistics
 
 [[sql-functions-aggs-kurtosis]]
 ===== `KURTOSIS`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+KURTOSIS(field_name<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
+
+*Output*: `double` numeric value
 
-https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values.
+.Description:
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggKurtosis]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-percentile]]
 ===== `PERCENTILE`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+PERCENTILE(field_name<1>, numeric_exp<2>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
+<2> a numeric expression
+
+*Output*: `double` numeric value
 
-The nth https://en.wikipedia.org/wiki/Percentile[percentile] of input values.
+.Description:
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+Returns the nth https://en.wikipedia.org/wiki/Percentile[percentile] (represented by `numeric_exp` parameter)
+of input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggPercentile]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-percentile-rank]]
 ===== `PERCENTILE_RANK`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+PERCENTILE_RANK(field_name<1>, numeric_exp<2>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
+<2> a numeric expression
 
-The https://en.wikipedia.org/wiki/Percentile_rank[percentile rank] of input values of input values.
+*Output*: `double` numeric value
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+.Description:
+
+Returns the nth https://en.wikipedia.org/wiki/Percentile_rank[percentile rank] (represented by `numeric_exp` parameter)
+of input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggPercentileRank]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-skewness]]
 ===== `SKEWNESS`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+SKEWNESS(field_name<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
+
+*Output*: `double` numeric value
+
+.Description:
 
-https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values.
+https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values in the field `field_name`.
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggSkewness]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-stddev-pop]]
 ===== `STDDEV_POP`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+STDDEV_POP(field_name<1>)
+--------------------------------------------------
 
-https://en.wikipedia.org/wiki/Standard_deviations[Population standard deviation] of input values.
+*Input*:
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+<1> a numeric field
+
+*Output*: `double` numeric value
+
+.Description:
+
+Returns the https://en.wikipedia.org/wiki/Standard_deviations[population standard deviation] of input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggStddevPop]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-sum-squares]]
 ===== `SUM_OF_SQUARES`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+SUM_OF_SQUARES(field_name<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
 
-https://en.wikipedia.org/wiki/Total_sum_of_squares[Sum of squares] of input values.
+*Output*: `double` numeric value
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+.Description:
+
+Returns the https://en.wikipedia.org/wiki/Total_sum_of_squares[sum of squares] of input values in the field `field_name`.
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggSumOfSquares]
-----
+--------------------------------------------------
 
 [[sql-functions-aggs-var-pop]]
 ===== `VAR_POP`
 
-*Input*: Numeric, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+VAR_POP(field_name<1>)
+--------------------------------------------------
+
+*Input*:
+
+<1> a numeric field
+
+*Output*: `double` numeric value
+
+.Description:
 
-https://en.wikipedia.org/wiki/Variance[Population] variance of input values.
+Returns the https://en.wikipedia.org/wiki/Variance[population variance] of input values in the field `field_name`.
 
-["source","sql",subs="attributes,callouts,macros"]
-----
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
 include-tagged::{sql-specs}/docs.csv-spec[aggVarPop]
-----
+--------------------------------------------------

docs/reference/sql/functions/conditional.asciidoc

@@ -10,10 +10,10 @@ Functions that return one of their arguments by evaluating in an if-else manner.
 [[sql-functions-conditional-coalesce]]
 ==== `COALESCE`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-COALESCE ( expression<1>, expression<2>, ... )
+COALESCE(expression<1>, expression<2>, ...)
 ----
 
 *Input*:
@@ -51,10 +51,10 @@ include-tagged::{sql-specs}/docs.csv-spec[coalesceReturnNull]
 [[sql-functions-conditional-ifnull]]
 ==== `IFNULL`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-IFNULL ( expression<1>, expression<2> )
+IFNULL(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -88,10 +88,10 @@ include-tagged::{sql-specs}/docs.csv-spec[ifNullReturnSecond]
 [[sql-functions-conditional-isnull]]
 ==== `ISNULL`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-ISNULL ( expression<1>, expression<2> )
+ISNULL(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -125,10 +125,10 @@ include-tagged::{sql-specs}/docs.csv-spec[isNullReturnSecond]
 [[sql-functions-conditional-nvl]]
 ==== `NVL`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-NVL ( expression<1>, expression<2> )
+NVL(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -162,10 +162,10 @@ include-tagged::{sql-specs}/docs.csv-spec[nvlReturnSecond]
 [[sql-functions-conditional-nullif]]
 ==== `NULLIF`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-NULLIF ( expression<1>, expression<2> )
+NULLIF(expression<1>, expression<2>)
 ----
 
 *Input*:
@@ -197,10 +197,10 @@ include-tagged::{sql-specs}/docs.csv-spec[nullIfReturnNull]
 [[sql-functions-conditional-greatest]]
 ==== `GREATEST`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-GREATEST ( expression<1>, expression<2>, ... )
+GREATEST(expression<1>, expression<2>, ...)
 ----
 
 *Input*:
@@ -239,10 +239,10 @@ include-tagged::{sql-specs}/docs.csv-spec[greatestReturnNull]
 [[sql-functions-conditional-least]]
 ==== `LEAST`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-LEAST ( expression<1>, expression<2>, ... )
+LEAST(expression<1>, expression<2>, ...)
 ----
 
 *Input*:

docs/reference/sql/functions/date-time.asciidoc

@@ -11,24 +11,20 @@ beta[]
 ==== Intervals
 
 A common requirement when dealing with date/time in general revolves around 
-the notion of ``interval``s, a topic that is worth exploring in the context of {es} and {es-sql}.
+the notion of `interval`, a topic that is worth exploring in the context of {es} and {es-sql}.
 
 {es} has comprehensive support for <<date-math, date math>> both inside <<date-math-index-names, index names>> and <<mapping-date-format, queries>>.
 Inside {es-sql} the former is supported as is by passing the expression in the table name, while the latter is supported through the standard SQL `INTERVAL`.
 
 The table below shows the mapping between {es} and {es-sql}:
 
-[cols="^m,^m",options="header"]
-
-|===
-|  {es}  | {es-sql}
-
+[cols="^m,^m"]
+|==========================
+s|{es}
+s|{es-sql}
 2+h| Index/Table date math
-
 2+|<index-{now/M{YYYY.MM}}>
-
 2+h| Query date math
-
 | 1y  | INTERVAL 1 YEAR
 | 2M  | INTERVAL 2 MONTH
 | 3w  | INTERVAL 21 DAY
@@ -36,8 +32,7 @@ The table below shows the mapping between {es} and {es-sql}:
 | 5h  | INTERVAL 5 HOUR
 | 6m  | INTERVAL 6 MINUTE
 | 7s  | INTERVAL 7 SECOND
-
-|===
+|==========================
 
 `INTERVAL` allows either `YEAR` and `MONTH` to be mixed together _or_ `DAY`, `HOUR`, `MINUTE` and `SECOND`.
 
@@ -45,11 +40,11 @@ TIP: {es-sql} accepts also the plural for each time unit (e.g. both `YEAR` and `
 
 Example of the possible combinations below:
 
-[cols="^,^",options="header"]
+[cols="^,^"]
 
 |===
-|  Interval                                     | Description
-                                              
+s|Interval
+s|Description
 | `INTERVAL '1-2' YEAR TO MONTH`                | 1 year and 2 months
 | `INTERVAL '3 4' DAYS TO HOURS`                | 3 days and 4 hours
 | `INTERVAL '5 6:12' DAYS TO MINUTES`           | 5 days, 6 hours and 12 minutes
@@ -58,7 +53,6 @@ Example of the possible combinations below:
 | `INTERVAL '123:45' HOUR TO MINUTES`           | 123 hours and 45 minutes
 | `INTERVAL '65:43:21.0123' HOUR TO SECONDS`    | 65 hours, 43 minutes, 21 seconds and 12300000 nanoseconds
 | `INTERVAL '45:01.23' MINUTES TO SECONDS`      | 45 minutes, 1 second and 230000000 nanoseconds
-
 |===
 
 ==== Operators
@@ -100,19 +94,18 @@ include-tagged::{sql-specs}/docs.csv-spec[dtIntervalMul]
 beta[]
 
 [[sql-functions-current-timestamp]]
-==== `CURRENT_TIMESTAMP`/`NOW`
+==== `CURRENT_TIMESTAMP`
 
 .Synopsis:
 [source, sql]
 --------------------------------------------------
 CURRENT_TIMESTAMP
 CURRENT_TIMESTAMP(precision <1>)
-NOW()
 --------------------------------------------------
 
 *Input*:
 
-<1> fractional digits - optional
+<1> fractional digits; optional
 
 *Output*: date/time
 
@@ -139,7 +132,8 @@ include-tagged::{sql-specs}/docs.csv-spec[curTsFunction]
 include-tagged::{sql-specs}/docs.csv-spec[curTsFunctionPrecision]
 --------------------------------------------------
 
-Typically this function is used for relative date/time filtering:
+Typically, this function (as well as its twin <<sql-functions-now,NOW())>> function is used for
+relative date/time filtering:
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -147,7 +141,7 @@ include-tagged::{sql-specs}/docs.csv-spec[filterNow]
 --------------------------------------------------
 
 [[sql-functions-datetime-day]]
-==== `DAY_OF_MONTH`/`DOM`/`DAY`
+==== `DAY_OF_MONTH/DOM/DAY`
 
 .Synopsis:
 [source, sql]
@@ -171,7 +165,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfMonth]
 --------------------------------------------------
 
 [[sql-functions-datetime-dow]]
-==== `DAY_OF_WEEK`/`DAYOFWEEK`/`DOW`
+==== `DAY_OF_WEEK/DAYOFWEEK/DOW`
 
 .Synopsis:
 [source, sql]
@@ -195,7 +189,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfWeek]
 --------------------------------------------------
 
 [[sql-functions-datetime-doy]]
-==== `DAY_OF_YEAR`/`DOY`
+==== `DAY_OF_YEAR/DOY`
 
 .Synopsis:
 [source, sql]
@@ -219,7 +213,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayOfYear]
 --------------------------------------------------
 
 [[sql-functions-datetime-dayname]]
-==== `DAY_NAME`/`DAYNAME`
+==== `DAY_NAME/DAYNAME`
 
 .Synopsis:
 [source, sql]
@@ -243,7 +237,7 @@ include-tagged::{sql-specs}/docs.csv-spec[dayName]
 --------------------------------------------------
 
 [[sql-functions-datetime-hour]]
-==== `HOUR_OF_DAY`/`HOUR`
+==== `HOUR_OF_DAY/HOUR`
 
 .Synopsis:
 [source, sql]
@@ -267,7 +261,7 @@ include-tagged::{sql-specs}/docs.csv-spec[hourOfDay]
 --------------------------------------------------
 
 [[sql-functions-datetime-isodow]]
-==== `ISO_DAY_OF_WEEK`/`ISODAYOFWEEK`/`ISODOW`/`IDOW`
+==== `ISO_DAY_OF_WEEK/ISODAYOFWEEK/ISODOW/IDOW`
 
 .Synopsis:
 [source, sql]
@@ -292,7 +286,7 @@ include-tagged::{sql-specs}/docs.csv-spec[isoDayOfWeek]
 --------------------------------------------------
 
 [[sql-functions-datetime-isoweek]]
-==== `ISO_WEEK_OF_YEAR`/`ISOWEEKOFYEAR`/`ISOWEEK`/`IWOY`/`IW`
+==== `ISO_WEEK_OF_YEAR/ISOWEEKOFYEAR/ISOWEEK/IWOY/IW`
 
 .Synopsis:
 [source, sql]
@@ -341,7 +335,7 @@ include-tagged::{sql-specs}/docs.csv-spec[minuteOfDay]
 --------------------------------------------------
 
 [[sql-functions-datetime-minute]]
-==== `MINUTE_OF_HOUR`/`MINUTE`
+==== `MINUTE_OF_HOUR/MINUTE`
 
 .Synopsis:
 [source, sql]
@@ -365,7 +359,7 @@ include-tagged::{sql-specs}/docs.csv-spec[minuteOfHour]
 --------------------------------------------------
 
 [[sql-functions-datetime-month]]
-==== `MONTH_OF_YEAR`/`MONTH`
+==== `MONTH_OF_YEAR/MONTH`
 
 .Synopsis:
 [source, sql]
@@ -389,7 +383,7 @@ include-tagged::{sql-specs}/docs.csv-spec[monthOfYear]
 --------------------------------------------------
 
 [[sql-functions-datetime-monthname]]
-==== `MONTH_NAME`/`MONTHNAME`
+==== `MONTH_NAME/MONTHNAME`
 
 .Synopsis:
 [source, sql]
@@ -412,8 +406,39 @@ Extract the month from a datetime in text format (`January`, `February`...).
 include-tagged::{sql-specs}/docs.csv-spec[monthName]
 --------------------------------------------------
 
+[[sql-functions-now]]
+==== `NOW`
+
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+NOW()
+--------------------------------------------------
+
+*Input*: _none_
+
+*Output*: date/time
+
+.Description:
+
+This function offers the same functionality as <<sql-functions-current-timestamp,CURRENT_TIMESTAMP()>> function: returns the date/time 
+when the current query reached the server. This method always returns the same value within a query.
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs.csv-spec[nowFunction]
+--------------------------------------------------
+
+Typically, this function (as well as its twin <<sql-functions-current-timestamp,CURRENT_TIMESTAMP())>> function is used for
+relative date/time filtering:
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs.csv-spec[filterNow]
+--------------------------------------------------
+
 [[sql-functions-datetime-second]]
-==== `SECOND_OF_MINUTE`/`SECOND`
+==== `SECOND_OF_MINUTE/SECOND`
 
 .Synopsis:
 [source, sql]
@@ -461,7 +486,7 @@ include-tagged::{sql-specs}/docs.csv-spec[quarter]
 --------------------------------------------------
 
 [[sql-functions-datetime-week]]
-==== `WEEK_OF_YEAR`/`WEEK`
+==== `WEEK_OF_YEAR/WEEK`
 
 .Synopsis:
 [source, sql]

docs/reference/sql/functions/grouping.asciidoc

@@ -11,11 +11,11 @@ as part of the <<sql-syntax-group-by, grouping>>.
 [[sql-functions-grouping-histogram]]
 ==== `HISTOGRAM`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-HISTOGRAM ( numeric_exp<1>,  numeric_interval<2>)
-HISTOGRAM ( date_exp<3>,  date_time_interval<4>)
+HISTOGRAM(numeric_exp<1>, numeric_interval<2>)
+HISTOGRAM(date_exp<3>, date_time_interval<4>)
 ----
 
 *Input*:

docs/reference/sql/functions/math.asciidoc

@@ -65,13 +65,11 @@ include-tagged::{sql-specs}/docs.csv-spec[mathInlineCbrtWithNegativeValue]
 [source, sql]
 --------------------------------------------------
 CEIL(numeric_exp<1>)
-CEILING(numeric_exp<2>)
 --------------------------------------------------
 
 *Input*:
 
 <1> numeric expression
-<2> numeric expression
 
 *Output*: integer or long numeric value
 
@@ -279,7 +277,7 @@ include-tagged::{sql-specs}/docs.csv-spec[mathInlinePowerNegative]
 --------------------------------------------------
 
 [[sql-functions-math-random]]
-===== `RANDOM`
+===== `RANDOM/RAND`
 
 .Synopsis:
 [source, sql]
@@ -334,7 +332,7 @@ include-tagged::{sql-specs}/docs.csv-spec[mathRoundWithNegativeParameter]
 --------------------------------------------------
 
 [[sql-functions-math-sign]]
-===== `SIGN`
+===== `SIGN/SIGNUM`
 
 .Synopsis:
 [source, sql]

docs/reference/sql/functions/operators.asciidoc

@@ -47,7 +47,7 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldLessThan]
 include-tagged::{sql-specs}/filter.sql-spec[whereBetween]
 --------------------------------------------------
 
-* `IS NULL`/`IS NOT NULL`
+* `IS NULL/IS NOT NULL`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -64,6 +64,8 @@ include-tagged::{sql-specs}/filter.sql-spec[whereWithInAndMultipleValues]
 [[sql-operators-logical]]
 === Logical Operators
 
+beta[]
+
 Boolean operator for evaluating one or two expressions.
 
 * `AND`
@@ -90,6 +92,8 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot]
 [[sql-operators-math]]
 === Math Operators
 
+beta[]
+
 Perform mathematical operations affecting one or two values.
 The result is a value of numeric type.
 

docs/reference/sql/functions/search.asciidoc

@@ -13,7 +13,17 @@ such as `0` or `NULL`.
 [[sql-functions-search-score]]
 ==== `SCORE`
 
-*Input*: None, *Output*: `double`
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+SCORE()
+--------------------------------------------------
+
+*Input*: _none_
+
+*Output*: `double` numeric value
+
+.Description:
 
 Returns the {defguide}/relevance-intro.html[relevance] of a given input to the executed query. 
 The higher score, the more relevant the data.

docs/reference/sql/functions/system.asciidoc

@@ -16,7 +16,7 @@ These functions return metadata type of information about the system being queri
 DATABASE()
 --------------------------------------------------
 
-*Input*:
+*Input*: _none_
 
 *Output*: string
 
@@ -39,14 +39,14 @@ include-tagged::{sql-specs}/docs.csv-spec[database]
 --------------------------------------------------
 USER()
 --------------------------------------------------
-*Input*:
+*Input*: _none_
 
 *Output*: string
 
 .Description:
 
 Returns the username of the authenticated user executing the query. This function can
-return `null` in case Security is disabled.
+return `null` in case {stack-ov}/elasticsearch-security.html[Security] is disabled.
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------

docs/reference/sql/functions/type-conversion.asciidoc

@@ -10,10 +10,10 @@ Functions for converting an expression of one data type to another.
 [[sql-functions-type-conversion-cast]]
 ==== `CAST`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-CAST ( expression<1> AS data_type<2> )
+CAST(expression<1> AS data_type<2>)
 ----
 
 <1> Expression to cast
@@ -44,10 +44,10 @@ include-tagged::{sql-specs}/docs.csv-spec[conversionStringToDateCast]
 [[sql-functions-type-conversion-convert]]
 ==== `CONVERT`
 
-.Synopsis
+.Synopsis:
 [source, sql]
 ----
-CONVERT ( expression<1>, data_type<2> )
+CONVERT(expression<1>, data_type<2>)
 ----
 
 <1> Expression to convert

docs/reference/sql/index.asciidoc

@@ -45,6 +45,8 @@ indices and return results in tabular format.
     syntax.
 <<sql-functions,Functions and Operators>>::
     List of functions and operators supported.
+<<sql-limitations,Limitations>>::
+    {es-sql} current limitations.
 --
 
 include::overview.asciidoc[]
@@ -55,5 +57,6 @@ include::endpoints/index.asciidoc[]
 include::language/index.asciidoc[]
 include::functions/index.asciidoc[]
 include::appendix/index.asciidoc[]
+include::limitations.asciidoc[]
 
 :jdbc-tests!:

docs/reference/sql/language/data-types.asciidoc

@@ -7,10 +7,12 @@ beta[]
 
 Most of {es} <<mapping-types, data types>> are available in {es-sql}, as indicated below:
 
-[cols="^,^m,^",options="header"]
+[cols="^,^m,^"]
 
 |===
-| {es} type                   | SQL type      | SQL precision
+s|{es} type
+s|SQL type
+s|SQL precision
 
 3+h| Core types
 
@@ -50,10 +52,11 @@ Such types cannot be loaded from {es} (as it does not know about them) however c
 
 The table below indicates these types:
 
-[cols="^m,^",options="header"]
+[cols="^m,^"]
 
 |===
-| SQL type                    | SQL precision
+s|SQL type
+s|SQL precision
 
 
 | interval_year             | 7

docs/reference/sql/language/index-patterns.asciidoc

@@ -62,9 +62,11 @@ an empty table is returned.
 
 In a nutshell, the differences between the two type of patterns are:
 
-[cols="^h,^,^",options="header"]
+[cols="^h,^,^"]
 |===
-| Feature | Multi index | SQL `LIKE`
+s|Feature
+s|Multi index
+s|SQL `LIKE`
 
 | Type of quoting    | `"` | `'`
 | Inclusion          | Yes | Yes

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

@@ -268,7 +268,7 @@ include-tagged::{sql-specs}/docs.csv-spec[groupByHavingMultiple]
 [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. ` 
+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.
 As such, the query emits only a single row (as there is only a single group) and `HAVING` condition returns either one row (the group) or zero if the condition fails.
 
 In this example, `HAVING` matches:
@@ -301,8 +301,8 @@ where:
 
 `expression`::
 
-Represents an input column, an output column or an ordinal number of the position (starting from one) of an output column. Additionally, ordering can be done based on the results _score_ ` 
-The direction, if not specified, is by default `ASC` (ascending). ` 
+Represents an input column, an output column or an ordinal number of the position (starting from one) of an output column. Additionally, ordering can be done based on the results _score_.
+The direction, if not specified, is by default `ASC` (ascending).
 Regardless of the ordering specified, null values are ordered last (at the end).
 
 IMPORTANT: When used along-side, `GROUP BY` expression can point _only_ to the columns used for grouping.

docs/reference/sql/limitations.asciidoc

@@ -0,0 +1,71 @@
+[role="xpack"]
+[testenv="basic"]
+[[sql-limitations]]
+== SQL Limitations
+
+beta[]
+
+[float]
+=== Nested fields in `SYS COLUMNS` and `DESCRIBE TABLE`
+
+{es} has a special type of relationship fields called `nested` fields. In {es-sql} they can be used by referencing their inner
+sub-fields. Even though `SYS COLUMNS` and `DESCRIBE TABLE` will still display them as having the type `NESTED`, they cannot
+be used in a query. One can only reference its sub-fields in the form:
+
+[source, sql]
+--------------------------------------------------
+[nested_field_name].[sub_field_name]
+--------------------------------------------------
+
+For example:
+
+[source, sql]
+--------------------------------------------------
+SELECT dep.dep_name.keyword FROM test_emp GROUP BY languages;
+--------------------------------------------------
+
+[float]
+=== Multi-nested fields
+
+{es-sql} doesn't support multi-nested documents, so a query cannot reference more than one nested field in an index.
+This applies to multi-level nested fields, but also multiple nested fields defined on the same level. For example, for this index:
+
+[source, sql]
+----------------------------------------------------
+       column         |     type      |    mapping
+----------------------+---------------+-------------
+nested_A              |STRUCT         |NESTED
+nested_A.nested_X     |STRUCT         |NESTED
+nested_A.nested_X.text|VARCHAR        |KEYWORD
+nested_A.text         |VARCHAR        |KEYWORD
+nested_B              |STRUCT         |NESTED
+nested_B.text         |VARCHAR        |KEYWORD
+----------------------------------------------------
+
+`nested_A` and `nested_B` cannot be used at the same time, nor `nested_A`/`nested_B` and `nested_A.nested_X` combination.
+For such situations, {es-sql} will display an error message.
+
+[float]
+=== Paginating nested inner hits
+
+When SELECTing a nested field, pagination will not work as expected, {es-sql} will return __at least__ the page size records. 
+This is because of the way nested queries work in {es}: the root nested field will be returned and it's matching inner nested fields as well,
+pagination taking place on the **root nested document and not on its inner hits**.
+
+[float]
+=== Normalized `keyword` fields
+
+`keyword` fields in {es} can be normalized by defining a `normalizer`. Such fields are not supported in {es-sql}.
+
+[float]
+=== Array type of fields
+
+Array fields are not supported due to the "invisible" way in which {es} handles an array of values: the mapping doesn't indicate whether
+a field is an array (has multiple values) or not, so without reading all the data, {es-sql} cannot know whether a field is a single or multi value.
+
+[float]
+=== Sorting by aggregation
+
+When doing aggregations (`GROUP BY`) {es-sql} relies on {es}'s `composite` aggregation for its support for paginating results.
+But this type of aggregation does come with a limitation: sorting can only be applied on the key used for the aggregation's buckets. This
+means that queries like `SELECT * FROM test GROUP BY age ORDER BY COUNT(*)` are not possible.

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

@@ -2128,5 +2128,5 @@ SELECT NOW() AS result;
          result         
 ------------------------
 2018-12-12T14:48:52.448Z
-// end::nowIgnore
+// end::nowFunction
 ;