From 27e945944bdb55de0e5362a2a89848fec5cfb45f Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 19 Jul 2023 11:00:34 -0400 Subject: [PATCH] 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 | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 8f9035f008..42f02268c9 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -20352,7 +20352,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); The right-hand side is a parenthesized list - of scalar expressions. The result is true if the left-hand expression's + of expressions. The result is true if the left-hand expression's result is equal to any of the right-hand expressions. This is a shorthand notation for @@ -20383,7 +20383,7 @@ OR The right-hand side is a parenthesized list - of scalar expressions. The result is true if the left-hand expression's + of expressions. The result is true if the left-hand expression's result is unequal to all of the right-hand expressions. This is a shorthand notation for @@ -20494,26 +20494,24 @@ AND Each side is a row constructor, as described in . - 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 operator is + The two row constructors must have the same number of fields. + The given operator 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 = member of a B-tree + operator class, meaning that row constructor comparison is only + possible when the operator is =, <>, <, <=, - > or - >=. - Every row element must be of a type which has a default B-tree operator - class or the attempted comparison may generate an error. + >, or + >=, + or has semantics similar to one of these. - - - Errors related to the number or types of elements might not occur if - the comparison is resolved using earlier columns. - - - The = and <> cases work slightly differently from the others. Two rows are considered