On Tue, Oct 24, 2023 at 06:45:48PM -0700, David G. Johnston wrote:
> I'd prefer to keep pointing out that the ones documented are those whose
> outputs will vary due to ordering.
Okay, I re-added it in the attached patch, and tightened up the text.
> I've been sympathetic to the user comments that we don't have enough examples.
Good point.
> Just using array_agg for that purpose, showing both DISTINCT and ORDER BY seems
> like a fair compromise (removes two from my original proposal). The examples
> in the section we tell them to go see aren't of that great quality. If you
> strongly dislike having the function table contain the examples we should at
> least improve the page we are sending them to. (As an aside to this, I've
> personally always found the syntax block with the 5 syntaxes shown there to be
> intimidating/hard-to-read).
I think you are right that it belongs in the syntax section; we cover
ordering extensively there. We already have queries there, but not
output, so I moved the relevant examples to there and replaced the
example that had no output.
> I'd at least suggest you reconsider the commentary and examples surrounding
> jsonb_object_agg.
I moved that as well, and tightened the example.
> The same goes for the special knowledge of floating point behavior for why
> we've chosen to document avg/sum, something that typically doesn't care about
> order, as having an optional order by.
The floating example seems too obscure to mention in our function docs.
I can put a sentence in the syntax docs, but is there value in
explaining that to users? How it that helpful? Example?
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.