Content-Type: text/plain;
	charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3826.700.81\))
Subject: Re: Document NULL
From: Chao Li <li.evan.chao@gmail.com>
In-Reply-To: <202511111530.xp4avso6b4pb@alvherre.pgsql>
Date: Fri, 14 Nov 2025 14:51:22 +0800
Cc: "David G. Johnston" <david.g.johnston@gmail.com>,
 jian he <jian.universality@gmail.com>,
 Jeff Davis <pgsql@j-davis.com>,
 Yugo NAGATA <nagata@sraoss.co.jp>,
 Tom Lane <tgl@sss.pgh.pa.us>,
 Peter Eisentraut <peter@eisentraut.org>,
 David Rowley <dgrowleyml@gmail.com>,
 PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>,
 Marcos Pegoraro <marcos@f10.com.br>
Content-Transfer-Encoding: quoted-printable
Message-Id: <F3FA26F6-9C35-4F9D-983E-6F653D11E437@gmail.com>
References: <202511111530.xp4avso6b4pb@alvherre.pgsql>
To: =?utf-8?Q?=C3=81lvaro_Herrera?= <alvherre@kurilemu.de>
Archived-At: 
 <https://www.postgresql.org/message-id/F3FA26F6-9C35-4F9D-983E-6F653D11E437%40gmail.com>
Precedence: bulk


> On Nov 11, 2025, at 23:34, =C3=81lvaro Herrera <alvherre@kurilemu.de> =
wrote:
>=20
> On 2025-Jun-18, David G. Johnston wrote:
>=20
>> Version 8.
>>=20
>> Marking this Ready to Commit in CF 2025-09 (CF PG19-1)
>=20
> I have rebased this; here's v9.  I haven't reviewed it in depth, but
> intend to give it a read and get it pushed sometime in the
> not-too-distant future, so if anybody wants to review it some more, =
it'd
> be appreciated.

I just reviewed this patch and got some comments:

>=20
> Note that this rebase was across the func.sgml split, which means I =
had
> to do some "manual" merging.  Looking at the git diff --stat output, =
it
> seems to match what was there before, so I don't think anything was
> lost.
>=20
> --=20
> =C3=81lvaro Herrera        Breisgau, Deutschland  =E2=80=94  =
https://www.EnterpriseDB.com/
> "Linux transform=C3=B3 mi computadora, de una `m=C3=A1quina para hacer =
cosas',
> en un aparato realmente entretenido, sobre el cual cada d=C3=ADa =
aprendo
> algo nuevo" (Jaime Salinas)
> <v9-0001-doc-Add-an-overview-of-NULL-treatment-in-PostgreS.patch>

1 - func-comparsions.sgml
```
+   tests are AND'd together.  Note that <literal>IS DISTINCT =
FROM</literal> is not an operator.
```

The =E2=80=9Cnote that=E2=80=9D sentence is not clear. I believe you =
meant to say the =E2=80=9CIS DISTINCT FROM=E2=80=9D cannot generate null =
values because it is not an operator. But one thing being not an =
operator doesn=E2=80=99t mean it cannot generate null value, right? So I =
think we=E2=80=99d be explicit, I am suggesting:

"Note that, IS DISTINCT FROM does not produce null results =E2=80=94 it =
always returns true or false."

This comment applies to 2 occurrences.

2 -  func-comparsions.sgml
```
+   Each side is evaluated and they are compared row-wise.
+   As discussed and shown in <xref =
linkend=3D"nullvalues-multielementcomparison-composite"/>,
+   null values are treated as being equal to other null values and =
greater
+   than all non-null values.
+   Composite type
    comparisons are allowed when the <replaceable>operator</replaceable> =
is
```

The =E2=80=9Ccomposite type=E2=80=9D line is too short, consider move =
the next line up.

3 -  func-comparsions.sgml
```
   <para>
-   If the array expression yields a null array, the result of
-   <token>ANY</token> will be null.  If the left-hand expression yields =
null,
-   the result of <token>ANY</token> is ordinarily null (though a =
non-strict
-   comparison operator could possibly yield a different result).
-   Also, if the right-hand array contains any null elements and no true
-   comparison result is obtained, the result of <token>ANY</token>
-   will be null, not false (again, assuming a strict comparison =
operator).
-   This is in accordance with SQL's normal rules for Boolean =
combinations
-   of null values.
+   If <replaceable>operator</replaceable> can produce null valued =
booleans then, as explained in
+   <xref linkend=3D"nullvalues-multielement"/>, it is not possible to =
see
+   a <quote>false</quote> result in the presence of both elements and =
null values since the multiple equality
+   tests are AND'd together.  Note that <literal>IS DISTINCT =
FROM</literal> is not an operator.
   </para>
```

For ANY, it should be =E2=80=9COR=E2=80=99d=E2=80=9D.

4 - func-subquery.sgml
```
   <para>
    The right-hand side is a parenthesized
-   subquery, which must return exactly one column.  The left-hand =
expression
+   subquery, which must return exactly one column.  The result of =
<token>IN</token>
+   is <quote>false</quote> if the subquery returns no rows, otherwise =
the left-hand expression
    is evaluated and compared to each row of the subquery result.
-   The result of <token>IN</token> is <quote>true</quote> if any equal =
subquery row is found.
-   The result is <quote>false</quote> if no equal row is found =
(including the
-   case where the subquery returns no rows).
+   The result is <quote>true</quote> if any equal subquery row is =
found.
+   The result is <quote>false</quote> if no equal row is found.
   </para>
=20
   <para>
-   Note that if the left-hand expression yields null, or if there are
-   no equal right-hand values and at least one right-hand row yields
-   null, the result of the <token>IN</token> construct will be null, =
not false.
-   This is in accordance with SQL's normal rules for Boolean =
combinations
-   of null values.
+   As explained in <xref linkend=3D"nullvalues-multielement"/>, it is =
not possible to see
+   a <quote>false</quote> result in the presence of both rows and null =
values since the multiple equality
+   tests are AND'd together.
   </para>
```

IN should be ORed.

5 -  func-subquery.sgml
```
   <para>
-   The right-hand side is a parenthesized
-   subquery, which must return exactly one column.  The left-hand =
expression
-   is evaluated and compared to each row of the subquery result.
-   The result of <token>NOT IN</token> is <quote>true</quote> if only =
unequal subquery rows
-   are found (including the case where the subquery returns no rows).
+   The right-hand side is a parenthesized subquery, which must return =
exactly one column.
+   The result of <token>NOT IN</token> is <quote>true</quote> if the =
subquery returns no rows,
+   otherwise the left-hand expression is evaluated and compared to each =
row of the subquery result.
+   The result is <quote>true</quote> if only unequal subquery rows are =
found.
    The result is <quote>false</quote> if any equal row is found.
   </para>
=20
   <para>
-   Note that if the left-hand expression yields null, or if there are
-   no equal right-hand values and at least one right-hand row yields
-   null, the result of the <token>NOT IN</token> construct will be =
null, not true.
-   This is in accordance with SQL's normal rules for Boolean =
combinations
-   of null values.
+   As explained in <xref linkend=3D"nullvalues-multielement"/>, it is =
not possible to see
+   a <quote>true</quote> result in the presence of both rows and null =
values since the multiple inequality
+   tests are OR'd together.
   </para>
```

NOT IN should be ANDed.

6 - func-subquery.sgml
```
-   The result of <token>ANY</token> is <quote>true</quote> if any true =
result is obtained.
-   The result is <quote>false</quote> if no true result is found =
(including the
-   case where the subquery returns no rows).
+   The result is <quote>true</quote> if any true result is obtained.
+   The result is <quote>false</quote> if no true result is found.
   </para>
=20
   <para>
@@ -223,11 +213,10 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 =3D =
tab1.col2);
   </para>
=20
   <para>
-   Note that if there are no successes and at least one right-hand row =
yields
-   null for the operator's result, the result of the <token>ANY</token> =
construct
-   will be null, not false.
-   This is in accordance with SQL's normal rules for Boolean =
combinations
-   of null values.
+   If <replaceable>operator</replaceable> can produce null valued =
booleans then, as explained in
+   <xref linkend=3D"nullvalues-multielement"/>, it is not possible to =
see
+   a <quote>false</quote> result in the presence of both rows and null =
values since the multiple equality
+   tests are AND'd together.  Note that <literal>IS DISTINCT =
FROM</literal> is not an operator.
   </para>
```

ANY should be OR-ed

7 - func-subquery.sgml
```
+   Note that <literal>IS DISTINCT FROM</literal> is not an operator.
```

Same as 1.

8 - nullvalues.sgml
```
+   to any other value (e.g., <literal>IS DISTINCT</literal>, and =
<literal>IS TRUE</literal>.)
```

Should =E2=80=9CIS DISTINCT=E2=80=9D be  =E2=80=9CIS DISTINCT FROM=E2=80=9D=
?

9 - nullvalues.sgml
```
+    all non-null valueS.
```

Nit typo. Should be small =E2=80=9Cs".

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/