docs: clarify SUM finalize returning None diverges from Elasticsearch

Surface the trade-off in the doc comment so future reviewers see why
this differs from ES (which returns "value": 0 for sum over
empty/all-missing buckets) and what consumers (ParadeDB SQL NULL) the
None variant is meant to serve.
This commit is contained in:
Mohammad Dashti 2026-04-27 15:04:37 -07:00 committed by PSeitz
commit 94fe52cc67

View file

@ -64,6 +64,14 @@ impl IntermediateSum {
/// Returns `None` when no values were collected (all documents had
/// missing/NULL values for the field), matching the behavior of
/// `IntermediateMin`, `IntermediateMax`, and `IntermediateAvg`.
///
/// Note: this diverges from Elasticsearch, which returns `"value": 0`
/// for sum aggregations over empty / all-missing buckets (min/max/avg
/// return `null`). Returning `None` here lets SQL-style consumers
/// (e.g. ParadeDB, where `SUM` of no rows is `NULL`) distinguish
/// "nothing was summed" from "values summed to 0" via the existing
/// `SingleMetricResult { value: Option<f64> }` boundary, which on
/// `main` is an `Option` that is never `None` for sum.
pub fn finalize(&self) -> Option<f64> {
let stats = self.stats.finalize();
if stats.count == 0 {