"there is no way to insert less than one row"

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/13/dml-insert.html
Description:

The documentation here says the following: "Of course you can also insert
more than one row, but there is no way to insert less than one row."
I tried this in psql:
---cut---
mydb=> create temporary table t1 (i1 int, v2 varchar(100));
CREATE TABLE
mydb=> create temporary table t2 (i1 int, v2 varchar(100));
CREATE TABLE
mydb=> insert into t2 select * from t1;
INSERT 0 0
mydb=>
---cut---
So, the last insert command inserted zero rows. What is meant by "there is
no way to insert less than one row"?

On 20.03.21 20:16, PG Doc comments form wrote:
> So, the last insert command inserted zero rows. What is meant by "there is
> no way to insert less than one row"?

I think the point was that you can't insert partial rows.

On Wed, Mar 24, 2021 at 1:29 PM Peter Eisentraut <
peter(dot)eisentraut(at)enterprisedb(dot)com> wrote:

> On 20.03.21 20:16, PG Doc comments form wrote:
> > So, the last insert command inserted zero rows. What is meant by "there
> is
> > no way to insert less than one row"?
>
> I think the point was that you can't insert partial rows.
>

Sure, if you think its related to the following sentence. If you think its
related to the subsequent one it means "cannot insert zero rows". Frankly,
both interpretations are wrong, inserting an explicit column list with
omitted columns populated using defaults is a "partial row API" for
inserting data.

I'm also not fond of the word "conceptually" here - its actually a physical
reality that regardless of how one or more rows are supplied they are
inserted one-at-a-time so far as constraints, discussed in the previous
chapter, are concerned (though some constraints can be deferred).

David J.

On 2021-Mar-24, David G. Johnston wrote:

> On Wed, Mar 24, 2021 at 1:29 PM Peter Eisentraut <
> peter(dot)eisentraut(at)enterprisedb(dot)com> wrote:
>
> > On 20.03.21 20:16, PG Doc comments form wrote:
> > > So, the last insert command inserted zero rows. What is meant by "there
> > is
> > > no way to insert less than one row"?
> >
> > I think the point was that you can't insert partial rows.
>
> Sure, if you think its related to the following sentence. If you think its
> related to the subsequent one it means "cannot insert zero rows". Frankly,
> both interpretations are wrong, inserting an explicit column list with
> omitted columns populated using defaults is a "partial row API" for
> inserting data.

Not really -- what you're doing in that case is insert a row that has
some null columns. It is still a complete row. I'm with Peter: the
idea being conveyed is that in tables, rows are atomic units.

> I'm also not fond of the word "conceptually" here - its actually a physical
> reality that regardless of how one or more rows are supplied they are
> inserted one-at-a-time so far as constraints, discussed in the previous
> chapter, are concerned (though some constraints can be deferred).

That doesn't seem a very interesting distinction, but I agree that this
can be worded differently to convey the idea of rows being the basic
units more clearly. Maybe something like this:

: When a table is created, it contains no data. The first thing to do
: before a database can be of much use is to insert data. Data is
: inserted one row at a time. Of course you can also insert
: more than one row in a single command, but it is not possible to
: insert something that is not a complete row.
: Even if you know only some column values, a complete row is created.

The next paragraphs explain that omitted columns are defaulted, which
IMO flows neatly from here.

(I would substitute "Of course you can also" with "It is possible to" ...
though that results in repetition of the word "possible" ... hmm.)

--
Álvaro Herrera 39°49'30"S 73°17'W

On 25.03.21 00:55, Alvaro Herrera wrote:
> : When a table is created, it contains no data. The first thing to do
> : before a database can be of much use is to insert data. Data is
> : inserted one row at a time. Of course you can also insert
> : more than one row in a single command, but it is not possible to
> : insert something that is not a complete row.
> : Even if you know only some column values, a complete row is created.
>
> The next paragraphs explain that omitted columns are defaulted, which
> IMO flows neatly from here.

done that way