SQL: [docs] Add documentation for COALESCE (#35740)

Follows: #35253

Author: Marios Trivyzas

docs/reference/sql/functions/conditional.asciidoc

@@ -0,0 +1,46 @@
+[role="xpack"]
+[testenv="basic"]
+[[sql-functions-conditional]]
+=== Conditional Functions
+
+Functions that return one of their arguments by evaluating in an if-else manner.
+
+[[sql-functions-conditional-coalesce]]
+==== `COALESCE`
+
+.Synopsis
+[source, sql]
+----
+COALESCE ( expression<1>, expression<2>, ... )
+----
+
+*Input*:
+
+<1> 1st expression
+
+<2> 2nd expression
+
+...
+
+**N**th expression
+
+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.
+If all arguments are null, then it returns `null`.
+
+
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs.csv-spec[coalesceReturnNonNull]
+----
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs.csv-spec[coalesceReturnNull]
+----

docs/reference/sql/functions/index.asciidoc

@@ -12,6 +12,7 @@
 * <<sql-functions-math, Mathematical>>
 * <<sql-functions-string, String>>
 * <<sql-functions-type-conversion,Type Conversion>>
+* <<sql-functions-conditional, Conditional>>
 
 include::operators.asciidoc[]
 include::aggs.asciidoc[]
@@ -20,3 +21,4 @@ include::search.asciidoc[]
 include::math.asciidoc[]
 include::string.asciidoc[]
 include::type-conversion.asciidoc[]
+include::conditional.asciidoc[]

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

@@ -1510,3 +1510,24 @@ SELECT TRUNCATE(-345.153, 1) AS trimmed;
 // end::mathTruncateWithPositiveParameter
 ;
 
+
+coalesceReturnNonNull
+// tag::coalesceReturnNonNull
+SELECT COALESCE(null, 'elastic', 'search') AS "coalesce";
+
+    coalesce
+---------------
+elastic
+// end::coalesceReturnNonNull
+;
+
+
+coalesceReturnNull
+// tag::coalesceReturnNull
+SELECT COALESCE(null, null, null, null) AS "coalesce";
+
+    coalesce
+---------------
+null
+// end::coalesceReturnNull
+;