SQL: document the use of a filter on _routing (#52355)

* Fix "Description"s for various sections in the functions pages.
* Added a TIP for searching using a routing key.
* Other small polishings

(cherry picked from commit 9fad0b1)

Author: astefan

docs/reference/sql/endpoints/jdbc.asciidoc

@@ -208,7 +208,8 @@ connection. For example:
 include-tagged::{jdbc-tests}/SimpleExampleTestCase.java[simple_example]
 --------------------------------------------------
 
-NOTE:: {es-sql} doesn't provide a connection pooling mechanism, thus the connections
+[NOTE]
+{es-sql} doesn't provide a connection pooling mechanism, thus the connections
 the JDBC driver creates are not pooled. In order to achieve pooled connections,
 a third-party connection pooling mechanism is required. Configuring and setting up the
 third-party provider is outside the scope of this documentation.

docs/reference/sql/endpoints/rest.asciidoc

@@ -370,6 +370,26 @@ Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T
 // TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
 // TESTRESPONSE[non_json]
 
+[TIP]
+=================
+A useful and less obvious usage for standard query DSL filtering is to search documents by a specific <<search-routing, routing key>>.
+Because {es-sql} does not support a `routing` parameter, one can specify a <<mapping-routing-field, `terms` filter for the `_routing` field>> instead:
+
+[source,console]
+--------------------------------------------------
+POST /_sql?format=txt
+{
+    "query": "SELECT * FROM library",
+    "filter": {
+        "terms": {
+            "_routing": ["abc"]
+        }
+    }
+}
+--------------------------------------------------
+// TEST[setup:library]
+=================
+
 [[sql-rest-columnar]]
 === Columnar results
 

docs/reference/sql/functions/aggs.asciidoc

@@ -25,9 +25,7 @@ AVG(numeric_field) <1>
 
 *Output*: `double` numeric value
 
-.Description:
-
-Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
+*Description*: Returns the https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -49,9 +47,7 @@ COUNT(expression) <1>
 
 *Output*: numeric value
 
-.Description:
-
-Returns the total number (count) of input values.
+*Description*: Returns the total number (count) of input values.
 
 In case of `COUNT(*)` or `COUNT(<literal>)`, _all_ values are considered (including `null` or missing ones).
 
@@ -79,9 +75,7 @@ COUNT(ALL field_name) <1>
 
 *Output*: numeric value
 
-.Description:
-
-Returns the total number (count) of all _non-null_ input values. `COUNT(<field_name>)` and `COUNT(ALL <field_name>)` are equivalent.
+*Description*: Returns the total number (count) of all _non-null_ input values. `COUNT(<field_name>)` and `COUNT(ALL <field_name>)` are equivalent.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -104,9 +98,7 @@ COUNT(DISTINCT field_name) <1>
 
 *Output*: numeric value
 
-.Description:
-
-Returns the total number of _distinct non-null_ values in input values.
+*Description*: Returns the total number of _distinct non-null_ values in input values.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -131,9 +123,7 @@ FIRST(
 
 *Output*: same type as the input
 
-.Description:
-
-Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by
+*Description*: Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by
 the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name`
 column is used for the sorting. E.g.:
 
@@ -228,10 +218,8 @@ LAST(
 
 *Output*: same type as the input
 
-.Description:
-
-It's the inverse of <<sql-functions-aggs-first>>. Returns the last **non-NULL** value (if such exists) of the
-`field_name`input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not
+*Description*: It's the inverse of <<sql-functions-aggs-first>>. Returns the last **non-NULL** value (if such exists) of the
+`field_name` input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not
 provided, only the `field_name` column is used for the sorting. E.g.:
 
 [cols="<,<"]
@@ -322,9 +310,7 @@ MAX(field_name) <1>
 
 *Output*: same type as the input
 
-.Description:
-
-Returns the maximum value across input values in the field `field_name`.
+*Description*: Returns the maximum value across input values in the field `field_name`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -350,9 +336,7 @@ MIN(field_name) <1>
 
 *Output*: same type as the input
 
-.Description:
-
-Returns the minimum value across input values in the field `field_name`.
+*Description*: Returns the minimum value across input values in the field `field_name`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -378,9 +362,7 @@ SUM(field_name) <1>
 
 *Output*: `bigint` for integer input, `double` for floating points
 
-.Description:
-
-Returns the sum of input values in the field `field_name`.
+*Description*: Returns the sum of input values in the field `field_name`.
 
 ["source","sql",subs="attributes,macros"]
 --------------------------------------------------
@@ -406,7 +388,7 @@ KURTOSIS(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values in the field `field_name`.
 
@@ -430,7 +412,7 @@ MAD(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 https://en.wikipedia.org/wiki/Median_absolute_deviation[Measure] the variability of the input values in the field `field_name`.
 
@@ -457,7 +439,7 @@ PERCENTILE(
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the nth https://en.wikipedia.org/wiki/Percentile[percentile] (represented by `numeric_exp` parameter)
 of input values in the field `field_name`.
@@ -485,7 +467,7 @@ PERCENTILE_RANK(
 
 *Output*: `double` numeric value
 
-.Description:
+*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`.
@@ -510,7 +492,7 @@ SKEWNESS(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values in the field `field_name`.
 
@@ -534,7 +516,7 @@ STDDEV_POP(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the https://en.wikipedia.org/wiki/Standard_deviations[population standard deviation] of input values in the field `field_name`.
 
@@ -558,7 +540,7 @@ SUM_OF_SQUARES(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the https://en.wikipedia.org/wiki/Total_sum_of_squares[sum of squares] of input values in the field `field_name`.
 
@@ -582,7 +564,7 @@ VAR_POP(field_name) <1>
 
 *Output*: `double` numeric value
 
-.Description:
+*Description*:
 
 Returns the https://en.wikipedia.org/wiki/Variance[population variance] of input values in the field `field_name`.
 

docs/reference/sql/functions/conditional.asciidoc

@@ -26,9 +26,7 @@ an _ELSE *default_result_* clause. Every *condition* should be a boolean express
 the *default_result* if all _WHEN *condition_* clauses evaluate to `false`. If the optional _ELSE *default_result_*
 clause is missing and all _WHEN *condition_* clauses evaluate to `false` then `null` is returned.
 
-.Description
-
-The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages
+*Description*: The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages
 If the condition’s result is true, the value of the result expression that follows the condition will be the returned
 the subsequent when clauses will be skipped and not processed.
 
@@ -148,9 +146,7 @@ COALESCE can take an arbitrary number of arguments.
 
 *Output*: one of the expressions or `null`
 
-.Description
-
-Returns the first of its arguments that is not null.
+*Description*: Returns the first of its arguments that is not null.
 If all arguments are null, then it returns `null`.
 
 
@@ -192,9 +188,7 @@ all of them must be of the same data type.
 
 *Output*: one of the expressions or `null`
 
-.Description
-
-Returns the argument that has the largest value which is not null.
+*Description*: Returns the argument that has the largest value which is not null.
 If all arguments are null, then it returns `null`.
 
 
@@ -229,9 +223,7 @@ IFNULL(
 
 *Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
-.Description
-
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+*Description*: 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`.
 
@@ -269,9 +261,7 @@ IIF(expression,   <1>
 *Output*: 2nd expression if 1st expression (condition) evaluates to `true`. If it evaluates to `false`
 return 3rd expression. If 3rd expression is not provided return `null`.
 
-.Description
-
-Conditional function that implements the standard _IF <condition> THEN <result1> ELSE <result2>_
+*Description*: Conditional function that implements the standard _IF <condition> THEN <result1> ELSE <result2>_
 logic of programming languages. If the 3rd expression is not provided and the condition evaluates to `false`,
 `null` is returned.
 
@@ -316,9 +306,7 @@ ISNULL(
 
 *Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
-.Description
-
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+*Description*: 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`.
 
@@ -362,9 +350,7 @@ all of them must be of the same data type.
 
 *Output*: one of the expressions or `null`
 
-.Description
-
-Returns the argument that has the smallest value which is not null.
+*Description*: Returns the argument that has the smallest value which is not null.
 If all arguments are null, then it returns `null`.
 
 
@@ -400,9 +386,7 @@ NULLIF(
 
 *Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
 
-.Description
-
-Returns `null` when the two input expressions are equal and
+*Description*: Returns `null` when the two input expressions are equal and
 if not, it returns the 1st expression.
 
 
@@ -437,9 +421,7 @@ NVL(
 
 *Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
 
-.Description
-
-Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
+*Description*: 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`.