doc: mention ORDER BY for some aggregates, add ORDER BY examples

Discussion: https://postgr.es/m/CAKFQuwb+4SWnfrfQKB-UM1P1x97Xk+ybSar4xM32XGLd=fq9bA@mail.gmail.com

Co-authored-by: David G. Johnston
Backpatch-through: master

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 5d5ad7ee6acf96cc3ddb9af3e78960f6b2afd2f6..a6fcac0824add8e13ab22c9dcabb15e2a1f26fac 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -20288,6 +20288,13 @@ SELECT NULLIF(value, '(none)') ...
    aggregation.
   
 
+  
+   While all aggregates below accept an optional
+   ORDER BY clause (as outlined in 
+   linkend="syntax-aggregates"/>), the clause has only been added to
+   aggregates whose output is affected by ordering.
+  
+
    
     General-Purpose Aggregate Functions
     
@@ -20325,7 +20332,7 @@ SELECT NULLIF(value, '(none)') ...
         
          array_agg
         
-        array_agg ( anynonarray )
+        array_agg ( anynonarray ORDER BY input_sort_columns )
         anyarray
        
        
@@ -20336,7 +20343,7 @@ SELECT NULLIF(value, '(none)') ...
 
       
        
-        array_agg ( anyarray )
+        array_agg ( anyarray ORDER BY input_sort_columns )
         anyarray
        
        
@@ -20541,14 +20548,14 @@ SELECT NULLIF(value, '(none)') ...
         
          json_agg
         
-        json_agg ( anyelement )
+        json_agg ( anyelement ORDER BY input_sort_columns )
         json
        
        
         
          jsonb_agg
         
-        jsonb_agg ( anyelement )
+        jsonb_agg ( anyelement ORDER BY input_sort_columns )
         jsonb
        
        
@@ -20588,7 +20595,8 @@ SELECT NULLIF(value, '(none)') ...
         
         json_object_agg ( key
          "any", value
-         "any" )
+         "any"
+         ORDER BY input_sort_columns )
         json
        
        
@@ -20597,7 +20605,8 @@ SELECT NULLIF(value, '(none)') ...
         
         jsonb_object_agg ( key
          "any", value
-         "any" )
+         "any"
+         ORDER BY input_sort_columns )
         jsonb
        
        
@@ -20834,7 +20843,8 @@ SELECT NULLIF(value, '(none)') ...
        
        
         string_agg ( value
-         bytea, delimiter bytea )
+         bytea, delimiter bytea
+         ORDER BY input_sort_columns )
         bytea
        
        
@@ -20892,7 +20902,7 @@ SELECT NULLIF(value, '(none)') ...
         
          xmlagg
         
-        xmlagg ( xml )
+        xmlagg ( xml ORDER BY input_sort_columns )
         xml
        
        


diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml

index 3ba844057fbddfc98b0647f8f5972ea3cd3f949f..9cee925a4836f80eff51527af935d183e9817684 100644 (file)

--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1647,7 +1647,20 @@ sqrt(2)
     are always just expressions and cannot be output-column names or numbers.
     For example:
 
-SELECT array_agg(a ORDER BY b DESC) FROM table;
+WITH vals (v) AS ( VALUES (1),(3),(4),(3),(2) )
+SELECT array_agg(v ORDER BY v DESC) FROM vals;
+  array_agg
+-------------
+ {4,3,3,2,1}
+
+    Since jsonb only keeps the last matching key, ordering
+    of its keys can be significant:
+
+WITH vals (k, v) AS ( VALUES ('key0','1'), ('key1','3'), ('key1','2') )
+SELECT jsonb_object_agg(k, v ORDER BY v) FROM vals;
+      jsonb_object_agg
+----------------------------
+ {"key0": "1", "key1": "3"}
 
    
 
@@ -1668,20 +1681,19 @@ SELECT string_agg(a ORDER BY a, ',') FROM table;  -- incorrect
    
 
    
-    If DISTINCT is specified in addition to an
-    order_by_clause, then all the ORDER BY
-    expressions must match regular arguments of the aggregate; that is,
-    you cannot sort on an expression that is not included in the
-    DISTINCT list.
+    If DISTINCT is specified with an
+    order_by_clause, ORDER
+    BY expressions can only reference columns in the
+    DISTINCT list.  For example:
+
+WITH vals (v) AS ( VALUES (1),(3),(4),(3),(2) )
+SELECT array_agg(DISTINCT v ORDER BY v DESC) FROM vals;
+ array_agg
+-----------
+ {4,3,2,1}
+
    
 
-   
-    
-     The ability to specify both DISTINCT and ORDER BY
-     in an aggregate function is a PostgreSQL extension.
-    
-   
-
    
     Placing ORDER BY within the aggregate's regular argument
     list, as described so far, is used when ordering the input rows for

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 3ba844057fbddfc98b0647f8f5972ea3cd3f949f..9cee925a4836f80eff51527af935d183e9817684 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1647,7 +1647,20 @@ sqrt(2)
     are always just expressions and cannot be output-column names or numbers.
     For example:
 
-SELECT array_agg(a ORDER BY b DESC) FROM table;
+WITH vals (v) AS ( VALUES (1),(3),(4),(3),(2) )
+SELECT array_agg(v ORDER BY v DESC) FROM vals;
+  array_agg
+-------------
+ {4,3,3,2,1}
+
+    Since jsonb only keeps the last matching key, ordering
+    of its keys can be significant:
+
+WITH vals (k, v) AS ( VALUES ('key0','1'), ('key1','3'), ('key1','2') )
+SELECT jsonb_object_agg(k, v ORDER BY v) FROM vals;
+      jsonb_object_agg
+----------------------------
+ {"key0": "1", "key1": "3"}
 
    
 
@@ -1668,20 +1681,19 @@ SELECT string_agg(a ORDER BY a, ',') FROM table;  -- incorrect
    
 
    
-    If DISTINCT is specified in addition to an
-    order_by_clause, then all the ORDER BY
-    expressions must match regular arguments of the aggregate; that is,
-    you cannot sort on an expression that is not included in the
-    DISTINCT list.
+    If DISTINCT is specified with an
+    order_by_clause, ORDER
+    BY expressions can only reference columns in the
+    DISTINCT list.  For example:
+
+WITH vals (v) AS ( VALUES (1),(3),(4),(3),(2) )
+SELECT array_agg(DISTINCT v ORDER BY v DESC) FROM vals;
+ array_agg
+-----------
+ {4,3,2,1}
+
    
 
-   
-    
-     The ability to specify both DISTINCT and ORDER BY
-     in an aggregate function is a PostgreSQL extension.
-    
-   
-
    
     Placing ORDER BY within the aggregate's regular argument
     list, as described so far, is used when ordering the input rows for