SELECT documentation

Hi,

The Examples section in the documentation for the SELECT command [1]

only contains a single example on how to join two tables,

which is written in SQL-89 style:

SELECT f.title, f.did, d.name, f.date_prod, f.kind

    FROM distributors d, films f

    WHERE f.did = d.did

I think it's good to keep this example query as it is,

and suggest we add the following equivalent queries:

SELECT f.title, f.did, d.name, f.date_prod, f.kind

    FROM distributors d

    JOIN films f ON f.did = d.did

SELECT f.title, f.did, d.name, f.date_prod, f.kind

    FROM distributors d

    JOIN films f USING (did)

SELECT f.title, f.did, d.name, f.date_prod, f.kind

    FROM distributors d

    NATURAL JOIN films f

I also think it would be an improvement to break up the from_item below into three separate items,

since the optional NATURAL cannot occur in combination with ON nor USING.

 

    from_item [ NATURAL ] join_type from_item [ ON join_condition | USING ( join_column [, ...] ) [ AS join_using_alias ] ]

Suggestion:

    from_item join_type from_item ON join_condition

 

This would be more readable imo.

I picked the order ON, USING, NATURAL to match the order they are described in the FROM Clause section.

/Joel

[1] https://www.postgresql.org/docs/current/sql-select.html