Doc: clarify description of degenerate NATURAL joins.

Claiming that NATURAL JOIN is equivalent to CROSS JOIN when there are
no common column names is only strictly correct if it's an inner join;
you can't say e.g. CROSS LEFT JOIN.  Better to explain it as meaning
JOIN ON TRUE, instead.  Per a suggestion from David Johnston.

Discussion: https://postgr.es/m/CAKFQuwb+mYszQhDS9f_dqRrk1=Pe-S6D=XMkAXcDf4ykKPmgKQ@mail.gmail.com

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 4094d72283104bb03965abd059c86d307db2b9a8..96c252bc28ee2fd30e49418929ecd0a7c1c19d35 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -393,8 +393,8 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
         consisting of all column names that appear in both
         input tables.  As with <literal>USING</>, these columns appear
         only once in the output table.  If there are no common
-        column names, <literal>NATURAL</literal> behaves like
-        <literal>CROSS JOIN</literal>.
+        column names, <literal>NATURAL JOIN</literal> behaves like
+        <literal>JOIN ... ON TRUE</literal>, producing a cross-product join.
        </para>
 
        <note>

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index c7fc50c5b82a4f0c640982acc86bbdb6050c3c89..820b8d47762b6752f937a2ea74d1a8178114b76d 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -538,9 +538,12 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
      <varlistentry>
       <term><literal>NATURAL</literal></term>
       <listitem>
-       <para><literal>NATURAL</literal> is shorthand for a
+       <para>
+        <literal>NATURAL</literal> is shorthand for a
         <literal>USING</> list that mentions all columns in the two
-        tables that have the same names.
+        tables that have matching names.  If there are no common
+        column names, <literal>NATURAL</literal> is equivalent
+        to <literal>ON TRUE</>.
        </para>
       </listitem>
      </varlistentry>