Re: COPY manual is ambiguous about column list

On Fri, Dec 20, 2019 at 7:13 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > OK, how is this?
>
> I do not like the phrasing of
>
> If a column list is
> specified in <command>COPY FROM</command>, the number and position of
> the columns must match those fields in the file.
>
> I'm not quite sure why, but that reads to me as implying that the COPY
> will identify columns of the file by name and match them up. Or at
> least it could be read that way by somebody who was predisposed to
> believe it. I'd go with something more like
>
> If a column list is
> specified in <command>COPY FROM</command>, only the listed columns
> are read from the file (whose fields must match the column list).
>

This has the same "match by name" possibility when I read it...

I don't see the benefit of repeating "If a column list is specified" a
second time in the three sentence paragraph. To a lesser extent the same
goes for the second repetition of COPY FROM.

I agree with the general goal of trying to get rid of the parenthetical; to
that end:
<command>COPY FROM</command> will match all listed columns in the table to
*all* file columns by position.

That sufficiently implies the "must have equal numbers" and, frankly, if
someone gets that part wrong the immediate failure combined with re-reading
the word "all" should provide sufficient clarity.

So I'm still for Tom and mine combined proposal with cleaning up the middle
sentence even more.

The other point of note is the difference between:

will receive their default value
and
will insert the default values

The system is inserting default values but the columns are receiving them.
The sentence is relative to the table columns though so "receive" seems
like the better fit. Minor point overall though.

David J.