Thread

Re: Document NULL

David G. Johnston <david.g.johnston@gmail.com> — 2025-11-14T14:25:54Z

On Fri, Nov 14, 2025 at 1:52 AM Chao Li <li.evan.chao@gmail.com> wrote:

> > On Nov 11, 2025, at 23:34, Álvaro Herrera <alvherre@kurilemu.de> wrote:
> >
> > On 2025-Jun-18, David G. Johnston wrote:
> >
> >> Version 8.
> >>
> >> Marking this Ready to Commit in CF 2025-09 (CF PG19-1)
> >
> > 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:
>
> >
> > 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.
>

Thanks for the review.  Still on extended travel sabbatical until December
so my full attention may not yet be here; and am not able to resubmit a new
patch version right now.  I'll do so in a couple of weeks, but appreciate
any assistance given.

>
> > --
> > Álvaro Herrera        Breisgau, Deutschland  —
> https://www.EnterpriseDB.com/
> > "Linux transformó mi computadora, de una `máquina para hacer cosas',
> > en un aparato realmente entretenido, sobre el cual cada día 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 “note that” sentence is not clear. I believe you meant to say the “IS
> DISTINCT FROM” cannot generate null values because it is not an operator.
> But one thing being not an operator doesn’t mean it cannot generate null
> value, right? So I think we’d be explicit, I am suggesting:
>
> "Note that, IS DISTINCT FROM does not produce null results — it always
> returns true or false."


> This comment applies to 2 occurrences.
>

Reading this again here, the first part where "operator cannot produce null
values" seems sufficient and calling out "is distinct from" can probably
just be removed instead of rephrased.


> 2 -  func-comparsions.sgml
> ```
> +   Each side is evaluated and they are compared row-wise.
> +   As discussed and shown in <xref
> linkend="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 “composite type” line is too short, consider move the next line up.
>

Yeah, some of the lines are broken purely for review patch diff
considerations.

>
> For ANY, it should be “OR’d”.
>

I very well may have flipped the AND/ORs around.


> 8 - nullvalues.sgml
> ```
> +   to any other value (e.g., <literal>IS DISTINCT</literal>, and
> <literal>IS TRUE</literal>.)
> ```
>
> Should “IS DISTINCT” be  “IS DISTINCT FROM”?
>

Probably.


> 9 - nullvalues.sgml
> ```
> +    all non-null valueS.
> ```
>
> Nit typo. Should be small “s".
>
>
Yeah.

David J.