Horton

Thread

Commits

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

  1. IN for records

    The Post Office <noreply@postgresql.org> — 2023-07-18T11:43:44Z

    The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/functions-comparisons.html
Description:

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) )"

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.

  2. Re: IN for records

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-07-18T18:14:10Z

    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

  3. Re: IN for records

    Ilya Nenashev <innenashev@gmail.com> — 2023-07-19T09:43:22Z

    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 <tgl@sss.pgh.pa.us> wrote:

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

  4. Re: IN for records

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-07-19T15:02:56Z

    Ilya Nenashev <innenashev@gmail.com> writes:
> I totally agree.
> Who and when will put these changes into the documentation pages?

Done at 
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=15c68cd84a2c80eed9b67ed6746ed5b91baea587

			regards, tom lane