7.2.1. The FROM Clause

On Fri, 2026-06-12 at 09:58 +0000, PG Doc comments form wrote:

I have a question regarding:
https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-FROM
Is the following sentence from the docu correct?
"Instead of writing ONLY before the table name, you can write * after the
table name to explicitly specify that descendant tables are included."

I read it like you can use "* after the table name" instead of "ONLY before
the table name" which seems wrong.

The "instead" does not mean that "tab *" is a substitute for "ONLY tab",
but is meant to mean that you cannot use both at the same time, like "ONLY tab *".

But I understand your confusion. To be honest, I only learned about the syntax
"tab *" a few days ago. Digging through the history, this syntax has been
obsolete since 2000. I think we could remove both the paragraph that confuses
you and the asterisk from the syntax diagram. We can leave the obsolete
syntax to accomodate SQL code that hasn't changed for over 25 years, but I don't
see a reason to keep it in the documentation.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

But I understand your confusion. To be honest, I only learned about the syntax
"tab *" a few days ago. Digging through the history, this syntax has been
obsolete since 2000. I think we could remove both the paragraph that confuses
you and the asterisk from the syntax diagram. We can leave the obsolete
syntax to accomodate SQL code that hasn't changed for over 25 years, but I don't
see a reason to keep it in the documentation.

I think we've discussed that before, and concluded that removing the
docs would be a disservice to users who are trying to read old code
that does this and don't know what it means. Maybe that argument
is too weak now to justify keeping the docs, but I'm unsure.
I'd be inclined to just rephrase this sentence in hopes of making
it less ambiguous.

regards, tom lane

On Sun, 2026-06-14 at 16:40 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

To be honest, I only learned about the syntax
"tab *" a few days ago. Digging through the history, this syntax has been
obsolete since 2000. I think we could remove both the paragraph that confuses
you and the asterisk from the syntax diagram.

I think we've discussed that before, and concluded that removing the
docs would be a disservice to users who are trying to read old code
that does this and don't know what it means. Maybe that argument
is too weak now to justify keeping the docs, but I'm unsure.
I'd be inclined to just rephrase this sentence in hopes of making
it less ambiguous.

Fine by me; here is a patch.

I could not resist the temptation to remove the "now always" in
"searching descendant tables is now always the default". That sounds
too much like this was a recent change.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

I could not resist the temptation to remove the "now always" in
"searching descendant tables is now always the default". That sounds
too much like this was a recent change.

Hmm, phrasing that part that way sounds like it's always been so,
which is not only false but is contradicted by the surrounding text.
What do you think of saying

There is no real reason to use this syntax
any more, because searching descendant tables has been the default
behavior since PostgreSQL whatever-version-it-was.

I can look up the version where it changed, if this seems like the way
to go.

I'm also tempted to replace "to use this syntax" with "to write *",
just to be totally clear which syntax we are referring to. After
your rewrite of the prior sentence, someone might think the closest
antecedent for "this" is "ONLY".

regards, tom lane

On Mon, 2026-06-15 at 11:05 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

I could not resist the temptation to remove the "now always" in
"searching descendant tables is now always the default".  That sounds
too much like this was a recent change.

Hmm, phrasing that part that way sounds like it's always been so,
which is not only false but is contradicted by the surrounding text.
What do you think of saying

    There is no real reason to use this syntax
    any more, because searching descendant tables has been the default
    behavior since PostgreSQL whatever-version-it-was.

I can look up the version where it changed, if this seems like the way
to go.

I did, and * became obsolete with 7.1. It's even in the release notes.

I'm also tempted to replace "to use this syntax" with "to write *",
just to be totally clear which syntax we are referring to.  After
your rewrite of the prior sentence, someone might think the closest
antecedent for "this" is "ONLY".

I am fine with both your suggestions.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Mon, 2026-06-15 at 11:05 -0400, Tom Lane wrote:

I can look up the version where it changed, if this seems like the way
to go.

I did, and * became obsolete with 7.1. It's even in the release notes.

Well, not really. 7.1 changed this behavior to depend on the
sql_inheritance GUC. It wasn't till v10 when we removed that GUC
(see e13486eba) that you could really safely assume that an
undecorated table name includes child tables. So I think we should
say it's obsolete since v10 not 7.1.

Pushed with those changes.

regards, tom lane

On Mon, 2026-06-15 at 13:14 -0400, Tom Lane wrote:

Pushed with those changes.

Thanks for improving PostgreSQL!

Laurenz Albe

Re: Tom Lane

I think we've discussed that before, and concluded that removing the
docs would be a disservice to users who are trying to read old code
that does this and don't know what it means. Maybe that argument
is too weak now to justify keeping the docs, but I'm unsure.

Fwiw, I saw that syntax somewhere some days back and then went looking
what it meant. I did find it in psql's "\h select" and in turn the
full SELECT documentation. I guess if the docs had not mentioned it, I
would have had to read the grammar, and looking for a non-string in
there sounds painful.

So it should definitely be kept. Thanks. :)

Christoph