Horton

Thread

Commits

  1. Doc: fix misleading syntax synopses for targetlists.

  1. INSERT ... RETURNING documentation

    The Post Office <noreply@postgresql.org> — 2024-07-25T20:35:01Z

    The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/sql-insert.html
Description:

The grammar
[ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
seems wrong to me. I appears to say it could be either
RETURNING *
or
output_expression [ [ AS ] output_name ] [, ...]

but I believe the RETURNING is always required.

  2. Re: INSERT ... RETURNING documentation

    David G. Johnston <david.g.johnston@gmail.com> — 2024-07-25T21:27:08Z

    On Thursday, July 25, 2024, PG Doc comments form <noreply@postgresql.org>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/16/sql-insert.html
> Description:
>
> The grammar
> [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
> seems wrong to me. I appears to say it could be either
> RETURNING *
> or
> output_expression [ [ AS ] output_name ] [, ...]
>
> but I believe the RETURNING is always required.
>

Yes, the word returning makes it the returning clause.  This should be
written:

[ Returning { * | output_expression [ [ AS ] output_name ] } [, …] ]

Here and on the update and delete pages.

Related, select says:

[ * | expression [ [ AS ] output_name ] [, …] ]

Shouldn’t this also be:

[ { * | expression [ [ AS ] output_name ] } [, …] ]

I know we do tend to let the reader infer exactly what the [, …] part
refers to but in this case it seems reasonably ambiguous.  I just think
most everyone learns how * works separately so it rarely comes up since no
one reads the syntax for it.


David J.

  3. Re: INSERT ... RETURNING documentation

    Tom Lane <tgl@sss.pgh.pa.us> — 2024-07-25T21:42:03Z

    "David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Thursday, July 25, 2024, PG Doc comments form <noreply@postgresql.org>
> wrote:
>> The grammar
>> [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
>> seems wrong to me.

> Yes, the word returning makes it the returning clause.  This should be
> written:

> [ Returning { * | output_expression [ [ AS ] output_name ] } [, …] ]

Agreed.

> Related, select says:

> [ * | expression [ [ AS ] output_name ] [, …] ]

I imagine the RETURNING synopsis was copied from that one :-(
Yes, let's change that too.

			regards, tom lane