From c8fd7ea97b29070691af57974f2f4d4f9d5fb12d Mon Sep 17 00:00:00 2001
From: Nik Everett <nik9000@gmail.com>
Date: Fri, 12 Jul 2024 13:00:08 -0400
Subject: [PATCH] Better

---
 docs/reference/esql/functions/count.asciidoc     | 16 ++++++++++++++--
 .../src/main/resources/stats.csv-spec            | 15 +++++++++++++++
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/reference/esql/functions/count.asciidoc b/docs/reference/esql/functions/count.asciidoc
index acbdcd9eeeb99..66cfe76350cdd 100644
--- a/docs/reference/esql/functions/count.asciidoc
+++ b/docs/reference/esql/functions/count.asciidoc
@@ -58,8 +58,20 @@ include::{esql-specs}/stats.csv-spec[tag=docsCountWithExpression-result]
 |===
 
 [[esql-agg-count-or-null]]
-To count the number of times an expression returns `TRUE`, use
-`COUNT(<expression> OR NULL)`:
+To count the number of times an expression returns `TRUE` use
+a <<esql-where>> command to remove rows that shouldn't be included:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/stats.csv-spec[tag=count-where]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/stats.csv-spec[tag=count-where-result]
+|===
+
+To count the same stream of data based on two different expressions
+use the pattern `COUNT(<expression> OR NULL)`:
 
 [source.merge.styled,esql]
 ----
diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec
index a0a7c178190cb..7b267027d2df8 100644
--- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec
+++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec
@@ -1158,6 +1158,21 @@ word_count:long
 // end::docsCountWithExpression-result[]
 ;
 
+count_or_null
+// tag::count-where[]
+ROW n=1
+| WHERE n < 0
+| STATS COUNT(n)
+// end::count-where[]
+;
+
+// tag::count-where-result[]
+COUNT(n):long
+            0
+// end::count-where-result[]
+;
+
+
 count_or_null
 // tag::count-or-null[]
 ROW n=1