Doc: clarify behavior of standard aggregates for null inputs.
authorTom Lane
Tue, 27 Aug 2019 20:37:22 +0000 (16:37 -0400)
committerTom Lane
Tue, 27 Aug 2019 20:37:22 +0000 (16:37 -0400)
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

index 169a01fc1a8521eeed266f8781fb89a361283564..6035c9751552d585e58a4ffffb160c23ef2afc32 100644 (file)
@@ -14602,7 +14602,7 @@ NULL baz(3 rows)
       No
       input arrays concatenated into array of one higher dimension
        (inputs must all have same dimensionality,
-        and cannot be empty or NULL)
+        and cannot be empty or null)
      
 
      
@@ -14626,7 +14626,7 @@ NULL baz(3 rows)
        otherwise the same as the argument data type
       
       Yes
-      the average (arithmetic mean) of all input values
+      the average (arithmetic mean) of all non-null input values
      
 
      
@@ -14754,7 +14754,7 @@ NULL baz(3 rows)
        json
       
       No
-      aggregates values as a JSON array
+      aggregates values, including nulls, as a JSON array
      
 
      
@@ -14771,7 +14771,7 @@ NULL baz(3 rows)
        jsonb
       
       No
-      aggregates values as a JSON array
+      aggregates values, including nulls, as a JSON array
      
 
      
@@ -14788,7 +14788,8 @@ NULL baz(3 rows)
        json
       
       No
-      aggregates name/value pairs as a JSON object
+      aggregates name/value pairs as a JSON object; values can be
+       null, but not names
      
 
      
@@ -14805,7 +14806,8 @@ NULL baz(3 rows)
        jsonb
       
       No
-      aggregates name/value pairs as a JSON object
+      aggregates name/value pairs as a JSON object; values can be
+       null, but not names
      
 
      
@@ -14821,7 +14823,7 @@ NULL baz(3 rows)
       Yes
       
        maximum value of 
-       class="parameter">expression across all input
+       class="parameter">expression across all non-null input
        values
       
      
@@ -14839,7 +14841,7 @@ NULL baz(3 rows)
       Yes
       
        minimum value of 
-       class="parameter">expression across all input
+       class="parameter">expression across all non-null input
        values
       
      
@@ -14861,7 +14863,7 @@ NULL baz(3 rows)
        same as argument types
       
       No
-      input values concatenated into a string, separated by delimiter
+      non-null input values concatenated into a string, separated by delimiter
      
 
      
@@ -14884,7 +14886,8 @@ NULL baz(3 rows)
        argument data type
       
       Yes
-      sum of expression across all input values
+      sum of expression
+       across all non-null input values
      
 
      
@@ -14901,7 +14904,8 @@ NULL baz(3 rows)
        xml
       
       No
-      concatenation of XML values (see also )
+      concatenation of non-null XML values
+       (see also )