Re: Please provide examples of rows from

On Thu, Sep 3, 2020 at 6:46 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Wed, Apr 8, 2020 at 09:50:44PM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/12/queries-table-expressions.html
> > Description:
> >
> > The explanation of ROWS FROM is fairly terse and no examples are given.
> >
> > As it is essentially impossible to usefully search for this phrase, it
> would
> > be helpful if at least a few examples were given.
>
> Looking at this suggestion, this was all I could think of:
>
> SELECT * FROM ROWS FROM (GENERATE_SERIES(1,10), GENERATE_SERIES(1,
> 15));
> generate_series | generate_series
> -----------------+-----------------
> 1 | 1
> 2 | 2
> 3 | 3
> 4 | 4
> 5 | 5
> 6 | 6
> 7 | 7
> 8 | 8
> 9 | 9
> 10 | 10
> (null) | 11
> (null) | 12
> (null) | 13
> (null) | 14
> (null) | 15
>
> The issue with adding an example is that it is hard to do something
> simple and have it illustrate anything. Does this help?
>

That documents one of the two variants - and incorporating the column alias
feature seems worthwhile for the chosen example. I do think this is worth
adding.

The more complicated one is the second:

ROWS FROM( ... function_call AS (column_definition [, ... ]) [, ... ] )

First, what's with the first set of "..."? It doesn't appear in the
reference documentation.

I was looking at the "Queries" doc comment a little bit ago and am
wondering if there is some principle by which we would decide to place any
new examples in this section versus the examples part of the SELECT
reference section?

I would note that part of the confusion probably stems from not defining
"column definition" in this chapter. It probably could be defined more
prominently in the SELECT reference as well.

Basically, aliases outside the ROWS FROM, column definitions within, unless
there is only a single "record" returning function involved (and without
ORDINALITY) in which case the external aliases can be instead a complete
column definition.

For the simple solution to the complaint I would thus suggest three
examples, but added to the SELECT reference, covering those three
situations (mutli-typed-aliased, multi-record,
single-rows-from-record-using-outside-columndef), and pointing the user to
the SELECT reference for said examples. That would be in addition to the
one example (another multi-typed-aliased) above being added to the queries
section.

A more involved patch would need, IMO, some structure to make the queries
section sufficient but less complex while relegating much of the complexity
to the reference section. That seems to be doing a better job describing
this reality presently anyway.

David J.