ESQL: Docs: COUNT: add an explanation to the use of the 3VL (elastic#…

…116684) Add an explanation of why `... OR NULL` is needed with `COUNT(...)`. Fixes: elastic#99954
pmpailis · Nov 19, 2024 · b5addca · b5addca
1 parent 25002fc
commit b5addca
Show file tree

Hide file tree

Showing 2 changed files with 4 additions and 2 deletions.
diff --git a/docs/reference/esql/functions/examples/count.asciidoc b/docs/reference/esql/functions/examples/count.asciidoc
diff --git a/.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Count.java b/.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Count.java
@@ -58,7 +58,9 @@ public class Count extends AggregateFunction implements ToAggregator, SurrogateE
             ),
             @Example(
                 description = "To count the same stream of data based on two different expressions "
-                    + "use the pattern `COUNT(<expression> OR NULL)`",
+                    + "use the pattern `COUNT(<expression> OR NULL)`. This builds on the three-valued logic "
+                    + "({wikipedia}/Three-valued_logic[3VL]) of the language: `TRUE OR NULL` is `TRUE`, but `FALSE OR NULL` is `NULL`, "
+                    + "plus the way COUNT handles `NULL`s: `COUNT(TRUE)` and `COUNT(FALSE)` are both 1, but `COUNT(NULL)` is 0.",
                 file = "stats",
                 tag = "count-or-null"
             ) }