Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1iiJmd-0003at-7W
	for pgsql-docs@arkaria.postgresql.org; Fri, 20 Dec 2019 15:01:39 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1iiJmb-0003vg-Np
	for pgsql-docs@arkaria.postgresql.org; Fri, 20 Dec 2019 15:01:37 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <bruce@momjian.us>)
	id 1iiJmb-0003vZ-C7
	for pgsql-docs@lists.postgresql.org; Fri, 20 Dec 2019 15:01:37 +0000
Received: from momjian.us ([72.94.173.45])
	by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1iiJmU-0006mQ-HP
	for pgsql-docs@lists.postgresql.org; Fri, 20 Dec 2019 15:01:36 +0000
Received: from bruce by momjian.us with local (Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1iiJmS-0005tx-Ru; Fri, 20 Dec 2019 10:01:28 -0500
Date: Fri, 20 Dec 2019 10:01:28 -0500
From: Bruce Momjian <bruce@momjian.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, Pavlo Golub <pavlo.golub@gmail.com>,
	Laurenz Albe <laurenz.albe@cybertec.at>,
	"pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Subject: Re: COPY manual is ambiguous about column list
Message-ID: <20191220150128.GD29807@momjian.us>
References: <4f3e2f301646d94ad33558e21fc77d5bf1ea1cdd.camel@cybertec.at>
 <CAMtUEpBmq3Mefkyh=RmkC4Fuqq+YtbUrr_nHnzxUwEbwm+CPfg@mail.gmail.com>
 <20191219165340.GP30116@momjian.us>
 <12751.1576817197@sss.pgh.pa.us>
 <CAKFQuwaxE-m5VKQkOapv+3kMnP2Q9hEb0NbGeBfqkQuX3UmVgQ@mail.gmail.com>
 <14696.1576819950@sss.pgh.pa.us>
 <CAKFQuwYHOpSfBcyX33Avt3ncrDsu6pxb-LXTm0SA+-nGWVSbhQ@mail.gmail.com>
 <20191220134541.GB29807@momjian.us>
 <3148.1576851213@sss.pgh.pa.us>
 <CAKFQuwa5RToC3+mbVGydTJZsqZhACK+F_CDtpcrCzxqwGXk6Cg@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="QKdGvSO+nmPlgiQ/"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKFQuwa5RToC3+mbVGydTJZsqZhACK+F_CDtpcrCzxqwGXk6Cg@mail.gmail.com>
User-Agent: Mutt/1.10.1 (2018-07-13)
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk


--QKdGvSO+nmPlgiQ/
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On Fri, Dec 20, 2019 at 07:29:33AM -0700, David G. Johnston wrote:
> 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.

OK, this wording is obviously harder than I thought.  Updated patch
attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

--QKdGvSO+nmPlgiQ/
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="copy.diff"

diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
new file mode 100644
index d9b7c4d..a99f815
*** a/doc/src/sgml/ref/copy.sgml
--- b/doc/src/sgml/ref/copy.sgml
*************** COPY { <replaceable class="parameter">ta
*** 61,71 ****
    </para>
  
    <para>
!    If a list of columns is specified, <command>COPY</command> will
!    only copy the data in the specified columns to or from the file.
!    If there are any columns in the table that are not in the column list,
!    <command>COPY FROM</command> will insert the default values for
!    those columns.
    </para>
  
    <para>
--- 61,71 ----
    </para>
  
    <para>
!    If a column list is specified, <command>COPY TO</command> copies only
!    the data in the specified columns to the file.  For <command>COPY
!    FROM</command>, each field in the file is inserted, in order, into the
!    specified column.  Table columns not specified in the <command>COPY
!    FROM</command> column list will receive their default values.
    </para>
  
    <para>

--QKdGvSO+nmPlgiQ/--