From 0a38a8ff3fb560ec9302cf06616ab4a4e6027c40 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Fri, 9 Oct 2026 22:14:29 -0400
Subject: [PATCH] doc:  add SQL query showing handling of NULLs by aggregates

Reported-by: y.saburov@gmail.com

Reviewed-by: Laurenz Albe

Discussion: https://postgr.es/m/178784080621.1060526.4544192651418189612@wrigleys.postgresql.org

Backpatch-through: 19
---
 doc/src/sgml/syntax.sgml | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

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>