postgres.git / summary / log / commit / refs
commit 15c68cd84a2c80eed9b67ed6746ed5b91baea587
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed Jul 19 15:00:34 2023 +0000
First released in: 17.0, 11.21, 12.16, 13.12, 14.9, 15.4, 16.0
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
doc/src/sgml/func.sgml | 43 ++++++++++++++-----------------------------
1 file changed, 14 insertions(+), 29 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 0b62e0c8285..b94827674c9 100644
--- 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><></literal>,
<literal><</literal>,
<literal><=</literal>,
- <literal>></literal> or
- <literal>>=</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>></literal>, or
+ <literal>>=</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><></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><</literal>, <literal><=</literal>, <literal>></literal> and <literal>>=</literal>
- cases were not handled per SQL specification. A comparison like
- <literal>ROW(a,b) < ROW(c,d)</literal>
- was implemented as
- <literal>a < c AND b < d</literal>
- whereas the correct behavior is equivalent to
- <literal>a < c OR (a = c AND b < d)</literal>.
- </para>
- </note>
-
<synopsis>
<replaceable>row_constructor</replaceable> IS DISTINCT FROM <replaceable>row_constructor</replaceable>
</synopsis>
[parent: 3f8c98d0b631]