Message-ID: <344e5b7d87a8c0e8e8f5f4924345b1caec1a4418.camel@cybertec.at>
Subject: Re: Improve "3.6. Inheritance" tutorial
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: =?ISO-8859-1?Q?Matem=E1tica?= A3K <matematica.a3k@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Date: Wed, 07 Oct 2026 16:43:52 +0200
In-Reply-To: 
 <CA+FDnhL0oygEJYZhDeAo+wwFykJeb__NNcO1+vyKSTqbTmQfvg@mail.gmail.com>
References: <179088091522.1026193.3570337969572056877@wrigleys.postgresql.org>
	 <3c6bdd69af16e90e3da20be277e836b25eeee1a5.camel@cybertec.at>
	 <CA+FDnhL0oygEJYZhDeAo+wwFykJeb__NNcO1+vyKSTqbTmQfvg@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.60.2 (3.60.2-2.fc44) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/344e5b7d87a8c0e8e8f5f4924345b1caec1a4418.camel%40cybertec.at>
Precedence: bulk

On Fri, 2026-10-02 at 12:23 -0300, Matem=C3=A1tica A3K wrote:
> On Fri, Oct 2, 2026 at 3:58=E2=80=AFAM Laurenz Albe <laurenz.albe@cyberte=
c.at> wrote:
> > On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> > > Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> > >=20
> > > I propose the following modifications: [...]
> >=20
> > Do I get you right that you don't have any problems with the
> > technical content, but are unhappy about the style?
>=20
> No, I'm unhappy with both, my suggestions go=C2=A0in both directions.

I must say that I perfer the original style.
But let's discuss the technical content:

> The main technical concern is that querying is not explained on it, it's
> explained on the "details page".
>
> More in concrete, if you add "In PostgreSQL, a table can inherit from zer=
o
> or more other tables, and a=C2=A0query can reference either all rows of a=
 table
> or all rows of a table plus=C2=A0all of its descendant tables. The latter=
 behavior
> is the default." should be a "complete" explanation of the feature.

I think the explanation in the tutorial is quite clear:

  Here the ONLY before cities indicates that the query should be run over
  only the cities table, and not tables below cities in the inheritance
  hierarchy. Many of the commands that we have already discussed =E2=80=94 =
SELECT,
  UPDATE, and DELETE =E2=80=94 support this ONLY notation.

A tutorial is not supposed to provide a rigorous definition.  Such a
definition should be in the reference manual.  And indeed I find in
https://www.postgresql.org/docs/18/sql-select.html

  If ONLY is specified before the table name, only that table is scanned.
  If ONLY is not specified, the table and all its descendant tables
  (if any) are scanned.

I'm happy with the page the way it is...

Yours,
Laurenz Albe