GFQL accepts sum()/avg() over BOOLEAN, which Cypher rejects — extension or conformance gap?

[lmeyerov]

Found by the aggregate x dtype differential sweep in #1819 (which pinned sum/avg to the Cypher
INTEGER | FLOAT | DURATION contract). This one is a deliberate GFQL extension that Cypher does
not allow, left in place there rather than changed silently — it needs an owner decision.

The divergence from Cypher

# Neo4j 5.26.26
UNWIND [true,false,true] AS x RETURN sum(x);
  -> Type mismatch: expected Float, Integer or Duration but was Boolean

GFQL, on every engine, answers 2:

import pandas as pd, graphistry
nodes = pd.DataFrame({"id": [0,1,2], "grp": ["x"]*3, "flag": [True, False, True]})
edges = pd.DataFrame({"src": [0], "dst": [1]})
g = graphistry.nodes(nodes, "id").edges(edges, "src", "dst")
g.gfql("MATCH (n) RETURN sum(n.flag) AS s", engine="pandas")._nodes   # -> s = 2
g.gfql("MATCH (n) RETURN avg(n.flag) AS a", engine="polars")._nodes   # -> a = 0.666...

Why it was NOT changed in #1819

• Both engines already agree, so it is not a divergence — it is a uniform extension.
• Summing an indicator column is idiomatic in the dataframe surface GFQL also serves, and rejecting
  it would break working user queries with no correctness argument behind the break.

It is recorded in graphistry/compute/gfql/agg_types.py as a choice with a reason rather than an
accident, so whoever revisits it finds the note. The decision to make is whether GFQL wants strict
Cypher conformance here (reject) or wants to keep the dataframe affordance (document it as an
explicit extension in the aggregates docs).

Repro harness: graphistry/tests/compute/gfql/test_aggregate_type_contract.py (the bool_col
parameters of the positive lane pin the current behaviour).

[lmeyerov]

Verdict: adopt the rule, with three amendments — measured, not assumed

Probed on dgx-spark, graphistry/test-rapids-official:26.02-gfql-polars, pandas nullable boolean and polars Boolean. cuDF was not probed; that arm is unverified.

input	pandas sum/mean/min/max/count	polars sum/mean/min/max/count
[T,F,T]	2 / 0.667 / F / T / 3	2 / 0.667 / F / T / 3
[T,null,F]	1 / 0.5 / F / T / 2	1 / 0.5 / F / T / 2
[null,null]	0 / NA / NA / NA / 0	0 / null / null / null / 0
[]	0 / NA / NA / NA / 0	0 / null / null / null / 0

On the populated rows the proposed rule is exactly what both engines already do. Adopting it costs nothing and breaks nothing. Three amendments:

1. Don't write min/max as AND/OR — it predicts the wrong answer on the empty case

min(bool) = AND, max(bool) = OR is a derivation from false < true, not a definition, and a logical fold is the natural way to implement it as written. The empty fold has the opposite identity: AND over zero elements is conventionally true, OR over zero elements false — but both engines return NULL. So a faithful implementation of the rule as stated diverges from the measured behaviour at precisely the all-null / empty row.

State it as ordering instead:

min/max over BOOLEAN use the standard boolean ordering false < true, and return NULL when there are no non-null values.

Same answer on populated input, correct on empty, and it composes with ORDER BY — which already orders booleans this way.

2. sum -> 0 on empty is Cypher-conformant — the rule is more defensible than the framing suggests

Cypher's sum() returns 0 over zero rows (SQL's SUM returns NULL); Cypher's avg() returns null. Both engines already match Cypher on both. So the sum=0 / avg=null asymmetry isn't a compromise to apologise for — it is the Cypher contract, and we get it for free.

Minor: the JavaScript null-as-zero comparison is beside the point here. The references that matter for this surface are Cypher, SQL, and pandas/polars, and the rule aligns with all three without needing that argument.

3. The real gap: the proposal pins values but not dtypes, and dtypes diverge today

agg	pandas	polars
sum	int64	UInt32
count	int64	UInt32
avg	float64	Float64 (agrees)

A contract that fixes values but not return types leaves exactly the cross-engine divergence class #1819 exists to close, and it's the same dtype/column-order axis that gates the auto-engine work. Pin it explicitly:

sum(BOOLEAN)   -> INTEGER (int64)     = count of true, nulls skipped; 0 over zero rows
avg(BOOLEAN)   -> FLOAT   (float64)   = true_count / non_null_count; NULL over zero non-null
min(BOOLEAN)   -> BOOLEAN             ordering false < true; NULL over zero non-null
max(BOOLEAN)   -> BOOLEAN             ordering false < true; NULL over zero non-null
count(BOOLEAN) -> INTEGER (int64)     non-null count

Extension vs reject

Adopt as a documented extension. It's already uniform across engines, summing an indicator column is idiomatic for the dataframe surface GFQL also serves, and it's a strict superset — no Cypher-valid query changes meaning, so the only cost is a doc line. Rejecting would break working queries with no correctness argument behind the break.

Register in #1665 (per-engine capability/semantics matrix) and #1664 (openCypher conformance tracker) so it reads as a deliberate divergence rather than an oversight.

This is cheap to do right now: #1819 already carries the type contract and the repro harness (test_aggregate_type_contract.py). What it still needs is the cuDF and polars-gpu arms, and negative tests on exactly the all-null / empty-group / mixed-null rows above — those are where the AND/OR reading and the dtype gap both surface.