postgres.git / summary / log / commit / refs

commit    fe50481899e890d5d2587fbd4748b658667dc71a
Author:   Tom Lane <tgl@sss.pgh.pa.us>
Date:     Tue Aug 27 20:37:22 2019 +0000
First released in: 13.0, 9.4.25, 9.5.20, 9.6.16, 10.11, 11.6, 12.0

    Doc: clarify behavior of standard aggregates for null inputs.
    
    Section 4.2.7 says that unless otherwise specified, built-in
    aggregates ignore rows in which any input is null.  This is
    not true of the JSON aggregates, but it wasn't documented.
    Fix that.
    
    Of the other entries in table 9.55, some were explicit about
    ignoring nulls, and some weren't; for consistency and
    self-contained-ness, make them all say it explicitly.
    
    Per bug #15884 from Tim Möhlmann.  Back-patch to all supported
    branches.
    
    Discussion: https://postgr.es/m/15884-c32d848f787fcae3@postgresql.org


 doc/src/sgml/func.sgml | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 8bac154d813..488fd967450 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -12200,7 +12200,7 @@ NULL baz</literallayout>(3 rows)</entry>
        <type>double precision</type> for a floating-point argument,
        otherwise the same as the argument data type
       </entry>
-      <entry>the average (arithmetic mean) of all input values</entry>
+      <entry>the average (arithmetic mean) of all non-null input values</entry>
      </row>
 
      <row>
@@ -12320,7 +12320,7 @@ NULL baz</literallayout>(3 rows)</entry>
       <entry>
        <type>json</type>
       </entry>
-      <entry>aggregates values as a JSON array</entry>
+      <entry>aggregates values, including nulls, as a JSON array</entry>
      </row>
 
      <row>
@@ -12336,7 +12336,8 @@ NULL baz</literallayout>(3 rows)</entry>
       <entry>
        <type>json</type>
       </entry>
-      <entry>aggregates name/value pairs as a JSON object</entry>
+      <entry>aggregates name/value pairs as a JSON object; values can be
+       null, but not names</entry>
      </row>
 
      <row>
@@ -12350,7 +12351,7 @@ NULL baz</literallayout>(3 rows)</entry>
       <entry>same as argument type</entry>
       <entry>
        maximum value of <replaceable
-       class="parameter">expression</replaceable> across all input
+       class="parameter">expression</replaceable> across all non-null input
        values
       </entry>
      </row>
@@ -12366,7 +12367,7 @@ NULL baz</literallayout>(3 rows)</entry>
       <entry>same as argument type</entry>
       <entry>
        minimum value of <replaceable
-       class="parameter">expression</replaceable> across all input
+       class="parameter">expression</replaceable> across all non-null input
        values
       </entry>
      </row>
@@ -12387,7 +12388,7 @@ NULL baz</literallayout>(3 rows)</entry>
       <entry>
        same as argument types
       </entry>
-      <entry>input values concatenated into a string, separated by delimiter</entry>
+      <entry>non-null input values concatenated into a string, separated by delimiter</entry>
      </row>
 
      <row>
@@ -12409,7 +12410,8 @@ NULL baz</literallayout>(3 rows)</entry>
        <type>bigint</type> arguments, otherwise the same as the
        argument data type
       </entry>
-      <entry>sum of <replaceable class="parameter">expression</replaceable> across all input values</entry>
+      <entry>sum of <replaceable class="parameter">expression</replaceable>
+       across all non-null input values</entry>
      </row>
 
      <row>
@@ -12425,7 +12427,8 @@ NULL baz</literallayout>(3 rows)</entry>
       <entry>
        <type>xml</type>
       </entry>
-      <entry>concatenation of XML values (see also <xref linkend="functions-xml-xmlagg">)</entry>
+      <entry>concatenation of non-null XML values
+       (see also <xref linkend="functions-xml-xmlagg">)</entry>
      </row>
     </tbody>
    </tgroup>


[parent: a5364a3df578]