Re: IN for records

PG Doc comments form <noreply@postgresql.org> writes:
> In section #FUNCTIONS-COMPARISONS-IN-SCALAR operator IN is described as a
> expression for scalars, and as a shorthand notation for a combination of
> operators || and =

> In section #COMPOSITE-TYPE-COMPARISON described extension, to use operators
> with a records, like "record operator record" for uncertain set of
> operators, and noted "Composite type comparisons are allowed when the
> operator is =, <>, <, <=, > or >=, or has semantics similar to one of
> these." and with a some difficult to understand note about B-trees.

> And as result, I can't see a direct description for allowance to use a
> syntax like a "(key_part_1, key_part_2) IN ( ('B',1), ('C',2) )"

I think perhaps you are reading too much into the word "scalar" in
the description of IN (and NOT IN).  In this context I believe it
just means "not a set-returning expression".  IN works fine on
container types such as records and arrays.

I'm inclined to propose that we simply drop the word "scalar" in
those two paragraphs.  It's adding more confusion than clarity.

> So I propose to mention record types in section
> #FUNCTIONS-COMPARISONS-IN-SCALAR. Phrase "The right-hand side is a
> parenthesized list of scalar expressions." can be replaced to phrases "The
> right-hand side is a parenthesized list of scalar or record expressions.
> About records [see further](#COMPOSITE-TYPE-COMPARISON)"
> Also I propose make similar adjustments in other sections of this page, and
> make cross-links here and in a
> https://www.postgresql.org/docs/current/functions-subquery.html page near
> the text mentions of each others.

I think this approach would end in a spaghetti mess of cross-references,
again adding more confusion than clarity.

I do agree that "9.24.5. Row Constructor Comparison" could use some work.
For starters, I think we should drop both of the existing <note> items.
The one about pre-8.2 bugs is surely long past its sell-by date.  As for
the other one, I have no idea what it's even talking about: we do resolve
all the comparison operators at parse time, and did so for years before
this note came in.  It's certainly too vague to be useful as it stands.

I don't much like "Every row element must be of a type which has a default
B-tree operator class or the attempted comparison may generate an error"
either, as it's confusing and not very accurate.  Looking at the code,
I think a better initial paragraph might be like

   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.
   The named operator is applied to each pair of corresponding row 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 the <literal>=</> member of a B-tree operator
   class, meaning that row constructor comparison is only possible
   when the <replaceable>operator</replaceable> is
   <literal>=</>,
   <literal>&lt;&gt;</>,
   <literal>&lt;</>,
   <literal>&lt;=</>,
   <literal>&gt;</> or
   <literal>&gt;=</>,
   or has semantics similar to one of these.

after which we can go on with the bit about "The = and <> cases work
slightly differently..."

                        regards, tom lane