rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

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 f56651519.)

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
This commit is contained in:
Tom Lane 2023-07-19 11:00:34 -04:00
parent e6e451c1d7
commit 245d0e6d0d
1 changed files with 14 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
doc/src/sgml/func.sgml
View File

@ -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>