doc: improve USING and NATURAL JOIN descriptions

Patch by David G Johnston

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 9bf3136f4b3129958b1d08bdd6be3b48d67ed157..c4a8ca8d8a450c2041cf035a4b15bac41cad46a4 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -245,25 +245,43 @@ FROM table_reference , table_r
         condition: it takes a Boolean value expression of the same
         kind as is used in a WHERE clause.  A pair of rows
         from T1 and T2 match if the
-        ON expression evaluates to true for them.
+        ON expression evaluates to true.
        
 
        
-        USING is a shorthand notation: it takes a
-        comma-separated list of column names, which the joined tables
-        must have in common, and forms a join condition specifying
-        equality of each of these pairs of columns.  Furthermore, the
-        output of JOIN USING has one column for each of
-        the equated pairs of input columns, followed by the
-        remaining columns from each table.  Thus, USING (a, b,
-        c) is equivalent to ON (t1.a = t2.a AND
-        t1.b = t2.b AND t1.c = t2.c) with the exception that
-        if ON is used there will be two columns
-        a, b, and c in the result,
-        whereas with USING there will be only one of each
-        (and they will appear first if SELECT * is used).
+        The USING clause allows you to take advantage of
+        the specific situation where both sides of the join use the
+        same name for the joining columns.  It takes a
+        comma-separated list of the shared column names
+        and forms a join using the equals operator.  Furthermore, the
+        output of JOIN USING has one column for each of the
+        listed columns, followed by the remaining columns from each table.
        
 
+       The output column difference between ON and
+       USING when invoking SELECT * is:
+         
+          
+           
+            ON - all columns from T1 followed
+            by all columns from T2
+           
+          
+          
+           
+            USING - all join columns, one copy each
+            and in the listed order, followed by non-join columns
+            in T1 followed by non-join columns in
+            T2
+           
+          
+          
+           
+            Examples provided below
+           
+          
+         
+
        
         
          join
@@ -281,6 +299,17 @@ FROM table_reference , table_r
         CROSS JOIN.
        
 
+       
+        
+         USING is reasonably safe from column changes
+         in the joined relations since only the specific columns mentioned
+         are considered.  NATURAL is considerably more problematic
+         if you are referring to relations only by name (views and tables)
+         since any schema changes to either relation that cause a new matching
+         column name to be present will cause the join to consider that new column.
+        
+       
+
        
         The possible types of qualified join are: