Thread

Re: Document NULL

David G. Johnston <david.g.johnston@gmail.com> — 2025-11-15T13:23:39Z

On Saturday, November 15, 2025, Peter Eisentraut <peter@eisentraut.org>
wrote:

> On 11.11.25 16:34, Álvaro Herrera 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.
>>
>
> > diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
> > index 948b9327f24..5ee0391d371 100644
> > --- a/doc/src/sgml/ddl.sgml
> > +++ b/doc/src/sgml/ddl.sgml
> > @@ -168,6 +168,8 @@ DROP TABLE products;
> >    </para>
> >   </sect1>
> >
> > + &nullvalues;
>
> I don't know if this is the right place for this section, if you
> follow the flow of the chapters.  The proposed text requires that you
> already know about DML, queries, data types, and functions, all of
> which come much later.the.


>
 Please make a concrete proposal of where to place it.  Ideally after
considering the discussion had a while back in the thread on this topic.

I also don't like the approach of this patch to pull out all of the
> null-related information from those various places and collect them
> all in one section.  I mean, that's interesting if you're really into
> studying null and how it affects various parts of SQL.  But if I'm
> like looking to use IS DISTINCT or whatever specific construct, then I
> want to get all the information relevant to that right there, not in
> various other places.
>

This section is a comprehensive review and place for examples pertaining to
the handling of null values.  Most of the feature sections already have the
relevant text present.  If they do not have sufficient commentary, that can
be added independently of this reference section.  There probably can be
quite a few more links from other places to here (I didn't really try on
these) and from here to those places (though I think I got those covered
fairly well) in a follow-on patch.

Null values introduce non-intuitive behaviors to the system and need to be
learned as a topic of study in order to safely operate the system.  There
is no way to glean the breadth of this cross-cutting oddity of the language
without someone having curated the information into a single place. (Well,
I suppose we could ensure that "Null values" is an index term and points to
every place for linking via the index - but this section seems both more
helpful and, while probably harder to accomplish, the hard work is
complete.)

David J.