Hi! Thanks.
I totally agree.
Who and when will put these changes into the documentation pages?
What can I do to make these changes faster?
On Tue, Jul 18, 2023 at 9:14 PM Tom Lane <t...@sss.pgh.pa.us> wrote:
> PG Doc comments form <nore...@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><></>,
> <literal><</>,
> <literal><=</>,
> <literal>></> or
> <literal>>=</>,
> 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
>
