Clarify documentation of handling of null arguments for aggregates.

Per discussion.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 66f72f321430677e74917cefd5218c3bfb6b9701..01fbd315b904dc8f64ab94eef04c1193c0a52c83 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   Functions and Operators
@@ -10034,7 +10034,7 @@ SELECT NULLIF(value, '(none)') ...
       
        array of the argument type
       
-      input values concatenated into an array
+      input values, including nulls, concatenated into an array
      
 
      

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index f3cff8ed2d81098fa60358000264fa6620d6ebf3..ca092b5ae6e50bfc21ff4e69e30d5e6f5d4da1a3 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  SQL Syntax
@@ -1541,23 +1541,29 @@ sqrt(2)
 
    
     The first form of aggregate expression invokes the aggregate
-    across all input rows for which the given expression(s) yield
-    non-null values.  (Actually, it is up to the aggregate function
-    whether to ignore null values or not — but all the standard ones do.)
+    once for each input row.
     The second form is the same as the first, since
-    ALL is the default.  The third form invokes the
-    aggregate for all distinct values of the expressions found
-    in the input rows (ignoring nulls if the function chooses to do so).
-    The last form invokes the aggregate once for
-    each input row regardless of null or non-null values; since no
+    ALL is the default.
+    The third form invokes the aggregate once for each distinct value
+    of the expression (or distinct set of values, for multiple expressions)
+    found in the input rows.
+    The last form invokes the aggregate once for each input row; since no
     particular input value is specified, it is generally only useful
     for the count(*) aggregate function.
    
 
+   
+    Most aggregate functions ignore null inputs, so that rows in which
+    one or more of the expression(s) yield null are discarded.  This
+    can be assumed to be true, unless otherwise specified, for all
+    built-in aggregates.
+   
+
    
     For example, count(*) yields the total number
     of input rows; count(f1) yields the number of
-    input rows in which f1 is non-null;
+    input rows in which f1 is non-null, since
+    count ignores nulls; and
     count(distinct f1) yields the number of
     distinct non-null values of f1.