Doc: improve description of IN and row-constructor comparisons.

tglsfdc · tglsfdc · commit 15c68cd84a2c · 2023-07-19T11:00:34.000-04:00
IN and NOT IN work fine on records and arrays, so just say that they accept "expressions" not "scalar expressions". I think that that phrasing was meant to say that they don't work on set-returning expressions, but that's not the common meaning of "scalar". Revise the description of row-constructor comparisons to make it perhaps a bit less confusing. (This partially reverts some dubious wording changes made by commit f566515.) Per gripe from Ilya Nenashev. Back-patch to supported branches. In HEAD and v16, also drop a NOTE about pre-8.2 behavior, which is hopefully no longer of interest to anybody. Discussion: https://postgr.es/m/168968062460.632.14303906825812821399@wrigleys.postgresql.org
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -22127,7 +22127,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
 
   <para>
    The right-hand side is a parenthesized list
-   of scalar expressions.  The result is <quote>true</quote> if the left-hand expression's
+   of expressions.  The result is <quote>true</quote> if the left-hand expression's
    result is equal to any of the right-hand expressions.  This is a shorthand
    notation for
 
@@ -22158,7 +22158,7 @@ OR
 
   <para>
    The right-hand side is a parenthesized list
-   of scalar expressions.  The result is <quote>true</quote> if the left-hand expression's
+   of expressions.  The result is <quote>true</quote> if the left-hand expression's
    result is unequal to all of the right-hand expressions.  This is a shorthand
    notation for
 
@@ -22269,26 +22269,24 @@ AND
   <para>
    Each side is a row constructor,
    as described in <xref linkend="sql-syntax-row-constructors"/>.
-   The two row values must have the same number of fields.
-   Each side is evaluated and they are compared row-wise.  Row constructor
-   comparisons are allowed when the <replaceable>operator</replaceable> is
+   The two row constructors must have the same number of fields.
+   The given <replaceable>operator</replaceable> is applied to each pair
+   of corresponding fields.  (Since the fields could be of different
+   types, this means that a different specific operator could be selected
+   for each pair.)
+   All the selected operators must be members of some B-tree operator
+   class, or be the negator of an <literal>=</literal> member of a B-tree
+   operator class, meaning that row constructor comparison is only
+   possible when the <replaceable>operator</replaceable> is
    <literal>=</literal>,
    <literal>&lt;&gt;</literal>,
    <literal>&lt;</literal>,
    <literal>&lt;=</literal>,
-   <literal>&gt;</literal> or
-   <literal>&gt;=</literal>.
-   Every row element must be of a type which has a default B-tree operator
-   class or the attempted comparison may generate an error.
+   <literal>&gt;</literal>, or
+   <literal>&gt;=</literal>,
+   or has semantics similar to one of these.
   </para>
 
-  <note>
-   <para>
-    Errors related to the number or types of elements might not occur if
-    the comparison is resolved using earlier columns.
-   </para>
-  </note>
-
   <para>
    The <literal>=</literal> and <literal>&lt;&gt;</literal> cases work slightly differently
    from the others.  Two rows are considered
@@ -22309,19 +22307,6 @@ AND
    considered.
   </para>
 
-  <note>
-   <para>
-    Prior to <productname>PostgreSQL</productname> 8.2, the
-    <literal>&lt;</literal>, <literal>&lt;=</literal>, <literal>&gt;</literal> and <literal>&gt;=</literal>
-    cases were not handled per SQL specification.  A comparison like
-    <literal>ROW(a,b) &lt; ROW(c,d)</literal>
-    was implemented as
-    <literal>a &lt; c AND b &lt; d</literal>
-    whereas the correct behavior is equivalent to
-    <literal>a &lt; c OR (a = c AND b &lt; d)</literal>.
-   </para>
-  </note>
-
 <synopsis>
 <replaceable>row_constructor</replaceable> IS DISTINCT FROM <replaceable>row_constructor</replaceable>
 </synopsis>
