Add an example to clarify the use of ORDER BY in multiple-argument

aggregates.  People seem to not get this right without help.

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index fcf5f161d8b55856d331b514f12bb73d5f0ff42a..16aa89f497f3cc2c7066f4acf48a4ae08e4b4742 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  SQL Syntax
@@ -1567,7 +1567,7 @@ sqrt(2)
     unspecified order.  In many cases this does not matter; for example,
     min produces the same result no matter what order it
     receives the inputs in.  However, some aggregate functions
-    (such as array_agg and xmlagg) produce
+    (such as array_agg and string_agg) produce
     results that depend on the ordering of the input rows.  When using
     such an aggregate, the optional order_by_clause can be
     used to specify the desired ordering.  The order_by_clause
@@ -1575,12 +1575,26 @@ sqrt(2)
     described in , except that its expressions
     are always just expressions and cannot be output-column names or numbers.
     For example:
-
 
 SELECT array_agg(a ORDER BY b DESC) FROM table;
 
    
 
+   
+    When dealing with multiple-argument aggregate functions, note that the
+    ORDER BY clause goes after all the aggregate arguments.
+    For example, this:
+
+SELECT string_agg(a, ',' ORDER BY a) FROM table;
+
+    not this:
+
+SELECT string_agg(a ORDER BY a, ',') FROM table;  -- not what you want
+
+    The latter syntax will be accepted, but ',' will be
+    treated as a (useless) sort key.
+   
+
    
     If DISTINCT is specified in addition to an
     order_by_clause, then all the ORDER BY