Doc: clarify data type behavior of COALESCE and NULLIF.

After studying the code, NULLIF is a lot more subtle than you might
have guessed.

Discussion: https://postgr.es/m/160486028730.25500.15740897403028593550@wrigleys.postgresql.org

2 files changed, 33 insertions, 6 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4d6992eec9e..903e52814d5 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -12497,6 +12497,12 @@ SELECT COALESCE(description, short_description, '(none)') ...
   </para>
 
    <para>
+    The arguments must all be convertible to a common data type, which
+    will be the type of the result (see
+    <xref linkend="typeconv-union-case"> for details).
+   </para>
+
+   <para>
     Like a <token>CASE</token> expression, <function>COALESCE</function> only
     evaluates the arguments that are needed to determine the result;
     that is, arguments to the right of the first non-null argument are
@@ -12526,13 +12532,30 @@ SELECT COALESCE(description, short_description, '(none)') ...
 <programlisting>
 SELECT NULLIF(value, '(none)') ...
 </programlisting>
-  </para>
-  <para>
    In this example, if <literal>value</literal> is <literal>(none)</>,
    null is returned, otherwise the value of <literal>value</literal>
    is returned.
   </para>
 
+  <para>
+   The two arguments must be of comparable types.
+   To be specific, they are compared exactly as if you had
+   written <literal><replaceable>value1</replaceable>
+   = <replaceable>value2</replaceable></literal>, so there must be a
+   suitable <literal>=</literal> operator available.
+  </para>
+
+  <para>
+   The result has the same type as the first argument &mdash; but there is
+   a subtlety.  What is actually returned is the first argument of the
+   implied <literal>=</literal> operator, and in some cases that will have
+   been promoted to match the second argument's type.  For
+   example, <literal>NULLIF(1, 2.2)</literal> yields <type>numeric</type>,
+   because there is no <type>integer</type> <literal>=</literal>
+   <type>numeric</type> operator,
+   only <type>numeric</type> <literal>=</literal> <type>numeric</type>.
+  </para>
+
   </sect2>
 
   <sect2 id="functions-greatest-least">
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index aa101088d30..03cfe51dc4d 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -127,8 +127,10 @@ must appear in a single set of columns, the types of the results of each
 <command>SELECT</> clause must be matched up and converted to a uniform set.
 Similarly, the result expressions of a <literal>CASE</> construct must be
 converted to a common type so that the <literal>CASE</> expression as a whole
-has a known output type.  The same holds for <literal>ARRAY</> constructs,
-and for the <function>GREATEST</> and <function>LEAST</> functions.
+has a known output type.  Some other constructs, such
+as <literal>ARRAY[]</literal> and the <function>GREATEST</function>
+and <function>LEAST</function> functions, likewise require determination of a
+common type for several subexpressions.
 </para>
 </listitem>
 </varlistentry>
@@ -1041,9 +1043,11 @@ SQL <literal>UNION</> constructs must match up possibly dissimilar
 types to become a single result set.  The resolution algorithm is
 applied separately to each output column of a union query.  The
 <literal>INTERSECT</> and <literal>EXCEPT</> constructs resolve
-dissimilar types in the same way as <literal>UNION</>.  The
+dissimilar types in the same way as <literal>UNION</>.
+Some other constructs, including
 <literal>CASE</>, <literal>ARRAY</>, <literal>VALUES</>,
-<function>GREATEST</> and <function>LEAST</> constructs use the identical
+and the <function>GREATEST</> and <function>LEAST</>
+functions, use the identical
 algorithm to match up their component expressions and select a result
 data type.
 </para>