BUG #14016: Incomplete documentation of IN subquery expression

The following bug has been logged on the website:

Bug reference: 14016
Logged by: Manlio Perillo
Email address: manlio(dot)perillo(at)gmail(dot)com
PostgreSQL version: 9.5.1
Operating system: Linux
Description:

At the end of the documentation for VALUE (sql-values.html), there is the
following tip:
"For simple IN tests, it's better to rely on the list-of-scalars form of IN
than to write a VALUES query as shown above"

However there is no reference to the "list-of-scalars" forms of IN, in the
functions-subquery.html page. It is only reported that the supported syntax
is "expression IN (subquery)"

The reference was available in an old version (7.3), where the manual
documented both the scalar form and sub query form:
"expression IN (value[, ...])"

On Fri, Mar 11, 2016 at 9:39 AM, <manlio(dot)perillo(at)gmail(dot)com> wrote:

> The following bug has been logged on the website:
>
> Bug reference: 14016
> Logged by: Manlio Perillo
> Email address: manlio(dot)perillo(at)gmail(dot)com
> PostgreSQL version: 9.5.1
> Operating system: Linux
> Description:
>
> At the end of the documentation for VALUE (sql-values.html), there is the
> following tip:
> "For simple IN tests, it's better to rely on the list-of-scalars form of IN
> than to write a VALUES query as shown above"
>
> However there is no reference to the "list-of-scalars" forms of IN, in the
> functions-subquery.html page. It is only reported that the supported
> syntax
> is "expression IN (subquery)"
>
> The reference was available in an old version (7.3), where the manual
> documented both the scalar form and sub query form:
> "expression IN (value[, ...])"
>

​It was moved...

​
http://www.postgresql.org/docs/9.5/interactive/functions-comparisons.html#AEN20283

​The interpretation being that a "list of scalars" is, in this situation,
semantically equivalent to an array - though having the later you would
have to use "=ANY(array)" instead of "IN"

​Apparently someone disagreed with the note in the subquery section:

>>>Note: This form of IN is not truly a subquery expression, but it seems
best to document it in the same place as subquery IN.

David J.

On Fri, Mar 11, 2016 at 10:02:01AM -0700, David G. Johnston wrote:
> On Fri, Mar 11, 2016 at 9:39 AM, <manlio(dot)perillo(at)gmail(dot)com> wrote:
>
> At the end of the documentation for VALUE (sql-values.html), there is the
> following tip:
> "For simple IN tests, it's better to rely on the list-of-scalars form of IN
> than to write a VALUES query as shown above"
>
> However there is no reference to the "list-of-scalars" forms of IN, in the
> functions-subquery.html page.  It is only reported that the supported
> syntax
> is "expression IN (subquery)"
>
> The reference was available in an old version (7.3), where the manual
> documented both the scalar form and sub query form:
> "expression IN (value[, ...])"
>
>
> ​It was moved...
>
> ​http://www.postgresql.org/docs/9.5/interactive/functions-comparisons.html#
> AEN20283
>
> ​The interpretation being that a "list of scalars" is, in this situation,
> semantically equivalent to an array - though having the later you would have to
> use "=ANY(array)" instead of "IN"
>
> ​Apparently someone disagreed with the note in the subquery section:
>
> >>>Note: This form of IN is not truly a subquery expression, but it seems best
> to document it in the same place as subquery IN.

Does the attached patch improve this?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +

On Tue, Apr 26, 2016 at 1:27 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Fri, Mar 11, 2016 at 10:02:01AM -0700, David G. Johnston wrote:
> > On Fri, Mar 11, 2016 at 9:39 AM, <manlio(dot)perillo(at)gmail(dot)com> wrote:
> >
> > At the end of the documentation for VALUE (sql-values.html), there
> is the
> > following tip:
> > "For simple IN tests, it's better to rely on the list-of-scalars
> form of IN
> > than to write a VALUES query as shown above"
> >
> > However there is no reference to the "list-of-scalars" forms of IN,
> in the
> > functions-subquery.html page. It is only reported that the supported
> > syntax
> > is "expression IN (subquery)"
> >
> > The reference was available in an old version (7.3), where the manual
> > documented both the scalar form and sub query form:
> > "expression IN (value[, ...])"
> >
> >
> > ​It was moved...
> >
> > ​
> http://www.postgresql.org/docs/9.5/interactive/functions-comparisons.html#
> > AEN20283
> >
> > ​The interpretation being that a "list of scalars" is, in this situation,
> > semantically equivalent to an array - though having the later you would
> have to
> > use "=ANY(array)" instead of "IN"
> >
> > ​Apparently someone disagreed with the note in the subquery section:
> >
> > >>>Note: This form of IN is not truly a subquery expression, but it
> seems best
> > to document it in the same place as subquery IN.
>
> Does the attached patch improve this?
>

​I'd append "scalar" to the id to distinguish in from the subquery
version. Otherwise any suggest I make seems like overkill. The main point
being the "list of scalars" is not a term we use on the referenced page,
and the chapter header indicates "Row and Array" of which this is similar
but technically neither.​

​<sect2 id="functions-comparisons-in-scalar"> [...]​

[...] rely on the ​<link
linkend="functions-comparison-in-scalar">array</link> form of [...]​

​David J.​

On Tue, Apr 26, 2016 at 02:00:39PM -0700, David G. Johnston wrote:
> On Tue, Apr 26, 2016 at 1:27 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > >>>Note: This form of IN is not truly a subquery expression, but it seems
> best
> > to document it in the same place as subquery IN.
>
> Does the attached patch improve this?
>
>
> ​I'd append "scalar" to the id to distinguish in from the subquery version. 
> Otherwise any suggest I make seems like overkill.  The main point being the
> "list of scalars" is not a term we use on the referenced page, and the chapter
> header indicates "Row and Array" of which this is similar but technically
> neither.​
>
> ​<sect2 id="functions-comparisons-in-scalar"> [...]​
>
> [...] rely on the ​<link linkend="functions-comparison-in-scalar">array</link>
> form of [...]​

Sorry, there was already a link in that place --- I had linked to the
wrong spot. New patch attached.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +

On Tuesday, April 26, 2016, Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Tue, Apr 26, 2016 at 02:00:39PM -0700, David G. Johnston wrote:
> > On Tue, Apr 26, 2016 at 1:27 PM, Bruce Momjian <bruce(at)momjian(dot)us
> <javascript:;>> wrote:
> > > >>>Note: This form of IN is not truly a subquery expression, but
> it seems
> > best
> > > to document it in the same place as subquery IN.
> >
> > Does the attached patch improve this?
> >
> >
> > ​I'd append "scalar" to the id to distinguish in from the subquery
> version.
> > Otherwise any suggest I make seems like overkill. The main point being
> the
> > "list of scalars" is not a term we use on the referenced page, and the
> chapter
> > header indicates "Row and Array" of which this is similar but technically
> > neither.​
> >
> > ​<sect2 id="functions-comparisons-in-scalar"> [...]​
> >
> > [...] rely on the ​<link
> linkend="functions-comparison-in-scalar">array</link>
> > form of [...]​
>
> Sorry, there was already a link in that place --- I had linked to the
> wrong spot. New patch attached.
>
>
I think the spot you linked to the first time was correct. The subquery
form is the one you get when using values, the scalar version is the one
the note wants to link to.

David J.

On Tue, Apr 26, 2016 at 05:32:04PM -0700, David G. Johnston wrote:
> I think the spot you linked to the first time was correct.  The subquery form
> is the one you get when using values, the scalar version is the one the note
> wants to link to.

OK, updated patch attached.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +

On Tuesday, April 26, 2016, Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Tue, Apr 26, 2016 at 05:32:04PM -0700, David G. Johnston wrote:
> > I think the spot you linked to the first time was correct. The subquery
> form
> > is the one you get when using values, the scalar version is the one the
> note
> > wants to link to.
>
> OK, updated patch attached.
>
>
Looks good. Thanks.

On Tue, Apr 26, 2016 at 08:41:33PM -0400, Bruce Momjian wrote:
> On Tue, Apr 26, 2016 at 05:32:04PM -0700, David G. Johnston wrote:
> > I think the spot you linked to the first time was correct.  The subquery form
> > is the one you get when using values, the scalar version is the one the note
> > wants to link to.
>
> OK, updated patch attached.

Patch applied.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +