doc: split out the NATURAL/CROSS JOIN in SELECT syntax

This allows the syntax to be more accurate about what clauses are
supported.  Also switch an example query to use the ANSI join syntax.

Reported-by: Joel Jacobson
Discussion: https://postgr.es/m/67b71d3e-0c22-44df-a223-351f14418319@www.fastmail.com

Backpatch-through: 11

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 410c80e730b02d776f7254240bdb3bc92ef931ce..1f9538f2feb300d907968cca53043cc78793a474 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -59,7 +59,9 @@ SELECT [ ALL | DISTINCT [ ON ( expression
     [ LATERAL ] function_name ( [ argument [, ...] ] ) AS ( column_definition [, ...] )
     [ LATERAL ] ROWS FROM( function_name ( [ argument [, ...] ] ) [ AS ( column_definition [, ...] ) ] [, ...] )
                 [ WITH ORDINALITY ] [ [ AS ] alias [ ( column_alias [, ...] ) ] ]
-    from_item [ NATURAL ] join_type from_item [ ON join_condition | USING ( join_column [, ...] ) [ AS join_using_alias ] ]
+    from_item join_type from_item { ON join_condition | USING ( join_column [, ...] ) [ AS join_using_alias ] }
+    from_item NATURAL join_type from_item
+    from_item CROSS JOIN from_item
 
 and grouping_element can be one of:
 
@@ -600,19 +602,15 @@ TABLE [ ONLY ] table_name [ * ]
          
           FULL [ OUTER ] JOIN
          
-         
-          CROSS JOIN
-         
         
 
         For the INNER and OUTER join types, a
         join condition must be specified, namely exactly one of
-        NATURAL, ON 
-        class="parameter">join_condition, or
+        ON 
+        class="parameter">join_condition,
         USING (
-        class="parameter">join_column [, ...]).
-        See below for the meaning.  For CROSS JOIN,
-        none of these clauses can appear.
+        class="parameter">join_column [, ...]),
+        or NATURAL.  See below for the meaning.
        
 
        
@@ -623,17 +621,9 @@ TABLE [ ONLY ] table_name [ * ]
         In the absence of parentheses, JOINs nest
         left-to-right.  In any case JOIN binds more
         tightly than the commas separating FROM-list items.
-       
-
-       CROSS JOIN and INNER JOIN
-        produce a simple Cartesian product, the same result as you get from
-        listing the two tables at the top level of FROM,
-        but restricted by the join condition (if any).
-        CROSS JOIN is equivalent to INNER JOIN ON
-        (TRUE), that is, no rows are removed by qualification.
-        These join types are just a notational convenience, since they
-        do nothing you couldn't do with plain FROM and
-        WHERE.
+        All the JOIN options are just a notational
+        convenience, since they do nothing you couldn't do with plain
+        FROM and WHERE.
        
 
        LEFT OUTER JOIN returns all rows in the qualified
@@ -714,6 +704,19 @@ TABLE [ ONLY ] table_name [ * ]
       
      
 
+     
+      CROSS JOIN
+      
+       
+        CROSS JOIN is equivalent to INNER JOIN ON
+        (TRUE), that is, no rows are removed by qualification.
+        They produce a simple Cartesian product, the same result as you get from
+        listing the two tables at the top level of FROM,
+        but restricted by the join condition (if any).
+       
+      
+     
+
      
       LATERAL
       
@@ -1754,8 +1757,7 @@ SELECT * FROM name
 
 
 SELECT f.title, f.did, d.name, f.date_prod, f.kind
-    FROM distributors d, films f
-    WHERE f.did = d.did
+    FROM distributors d JOIN films f USING (did);
 
        title       | did |     name     | date_prod  |   kind
 -------------------+-----+--------------+------------+----------




This is the main PostgreSQL git repository.
RSS
Atom