From b1818dbdcee2847b821ab75d7f72c24f5f0a0046 Mon Sep 17 00:00:00 2001
From: Marios Trivyzas <marios.trivyzas@elastic.co>
Date: Wed, 21 Nov 2018 01:43:05 +0100
Subject: [PATCH] SQL: [docs] Add documentation for COALESCE (#35740)

Follows: #35253
---
 .../sql/functions/conditional.asciidoc        | 46 +++++++++++++++++++
 docs/reference/sql/functions/index.asciidoc   |  2 +
 .../sql/qa/src/main/resources/docs.csv-spec   | 21 +++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 docs/reference/sql/functions/conditional.asciidoc

diff --git a/docs/reference/sql/functions/conditional.asciidoc b/docs/reference/sql/functions/conditional.asciidoc
new file mode 100644
index 0000000000000..6879c4816b48e
--- /dev/null
+++ b/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]
+----
diff --git a/docs/reference/sql/functions/index.asciidoc b/docs/reference/sql/functions/index.asciidoc
index 82e8154de93c9..97115748fe982 100644
--- a/docs/reference/sql/functions/index.asciidoc
+++ b/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[]
diff --git a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec b/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
index ccb9498f3590a..b965bfbe082e7 100644
--- a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
+++ b/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
+;