Document aggregate functions better w.r.t. ORDER BY

All,

The recent discussion surrounding aggregates and ORDER BY moved me to look
over our existing documentation, especially now that we've reworked the
function tables, to see what improvements can be had by simply documenting
those functions where ORDER BY may change the user-visible output. I
skipped range aggregates for the moment but handled the others on the
aggregates page (not window functions). This includes the float types for
sum and avg.

I added a note just before the table linking back to the syntax chapter and
describing the newly added rules and syntax choice in the table.

The nuances of floating point math suggest to me that specifying order by
for those is in some kind of gray area and so I've marked it optional...any
suggestions for wording (or an xref) to explain those nuances or should it
just be shown non-optional like the others? Or not shown at all?

The novelty of my examples is up for bikeshedding. I didn't want
anything too long so a subquery didn't make sense, and I was trying to
avoid duplication as well as multiple lines - hence creating a CTE that can
be copied onto all of the example queries to produce the noted result.

I added a DISTINCT example to array_agg because it is the first aggregate
on the page and so hopefully will be seen during a cursory reading. Plus,
array_agg is the go-to function for doing this kind of experimentation.

David J.

The patch is attached. A screenshot exemplifying the changes is copied
inline and attached.

[image: image.png]