Date: Tue, 15 Sep 2026 17:28:31 -0400
From: Bruce Momjian <bruce@momjian.us>
To: y.saburov@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: 4.2.7. Aggregate Expressions
Message-ID: <aqm4f5EZUdcSKh1C@momjian.us>
References: <178784080621.1060526.4544192651418189612@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="lXZ3FJDUs0lZTRJz"
Content-Disposition: inline
In-Reply-To: 
 <178784080621.1060526.4544192651418189612@wrigleys.postgresql.org>
Archived-At: 
 <https://www.postgresql.org/message-id/aqm4f5EZUdcSKh1C%40momjian.us>
Precedence: bulk


--lXZ3FJDUs0lZTRJz
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Thu, Aug 27, 2026 at 02:26:46PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/18/sql-expressions.html
> Description:
> 
> Can you add a code block with an example?
> 
> Perhaps something like this:
> 
> ```psql
> db=# WITH vals (f1) AS ( VALUES (1),(3),(4),(3),(2),(null) )
> SELECT count(*), count(f1), COUNT(DISTINCT f1) FROM vals;
> 
> count | count | count
> -------+-------+-------
>       6 |      5 |     4
> (1 row)
> ```
> 
> After:
> 
> >> For example, count(*) returns the total number of input rows; count(f1)
> returns the number of input rows in which f1 is not null, since count
> ignores null values; and count(distinct f1) returns the number of distinct
> non-null values of f1.

I see your point that this could be clearer.  How is this patch?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Do not let urgent matters crowd out time for investment in the future.

--lXZ3FJDUs0lZTRJz
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="agg_null.diff"

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 67482996861..a697218c8b3 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1602,11 +1602,19 @@ sqrt(2)
    </para>
 
    <para>
-    For example, <literal>count(*)</literal> yields the total number
-    of input rows; <literal>count(f1)</literal> yields the number of
-    input rows in which <literal>f1</literal> is non-null, since
-    <function>count</function> ignores nulls; and
-    <literal>count(distinct f1)</literal> yields the number of
+    For example, in this query:
+<programlisting>
+WITH vals (f1) AS ( VALUES (1),(3),(4),(3),(2),(null) )
+SELECT count(*) AS total, count(f1) AS non_null, COUNT(DISTINCT f1) AS distinct
+FROM vals;
+ total | non_null | distinct
+-------+----------+----------
+     6 |        5 |        4
+</programlisting>
+    <literal>total</literal> yields the total number of input rows;
+    <literal>non_null</literal> yields the number of input rows in which
+    <literal>f1</literal> is non-null, since <function>count</function>
+    ignores nulls; and <literal>distinct</literal> yields the number of
     distinct non-null values of <literal>f1</literal>.
    </para>
 

--lXZ3FJDUs0lZTRJz--