From 032f3b7e166cfa2818b0a9572324e362bf8895df Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 13 Oct 2014 15:39:49 -0400
Subject: [PATCH] doc: improve USING and NATURAL JOIN descriptions
Patch by David G Johnston
---
doc/src/sgml/queries.sgml | 57 +++++++++++++++++++++++++++++----------
1 file changed, 43 insertions(+), 14 deletions(-)
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 9bf3136f4b3..c4a8ca8d8a4 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -245,25 +245,43 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
condition: it takes a Boolean value expression of the same
kind as is used in a <literal>WHERE</> clause. A pair of rows
from <replaceable>T1</> and <replaceable>T2</> match if the
- <literal>ON</> expression evaluates to true for them.
+ <literal>ON</> expression evaluates to true.
</para>
<para>
- <literal>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 <literal>JOIN USING</> has one column for each of
- the equated pairs of input columns, followed by the
- remaining columns from each table. Thus, <literal>USING (a, b,
- c)</literal> is equivalent to <literal>ON (t1.a = t2.a AND
- t1.b = t2.b AND t1.c = t2.c)</literal> with the exception that
- if <literal>ON</> is used there will be two columns
- <literal>a</>, <literal>b</>, and <literal>c</> in the result,
- whereas with <literal>USING</> there will be only one of each
- (and they will appear first if <command>SELECT *</> is used).
+ The <literal>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 <literal>JOIN USING</> has one column for each of the
+ listed columns, followed by the remaining columns from each table.
</para>
+ <para>The output column difference between <literal>ON</> and
+ <literal>USING</> when invoking <literal>SELECT *</> is:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>ON</> - all columns from <replaceable>T1</> followed
+ by all columns from <replaceable>T2</>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>USING</> - all join columns, one copy each
+ and in the listed order, followed by non-join columns
+ in <replaceable>T1</> followed by non-join columns in
+ <replaceable>T2</>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Examples provided below
+ </para>
+ </listitem>
+ </itemizedlist>
+
<para>
<indexterm>
<primary>join</primary>
@@ -281,6 +299,17 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<literal>CROSS JOIN</literal>.
</para>
+ <note>
+ <para>
+ <literal>USING</literal> is reasonably safe from column changes
+ in the joined relations since only the specific columns mentioned
+ are considered. <literal>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.
+ </para>
+ </note>
+
<para>
The possible types of qualified join are:
--
GitLab