feat: ungrouped vectorized aggregate with a batch fold (#289)

[ChronicallyJD]

What

Addresses #289: a full-scan ungrouped aggregate that a zone map cannot answer (one with a WHERE filter, or sum/avg over int8/float/numeric) ran on the row-wise core Agg. This folds the decoded column buffer directly instead. Behind pgcolumnar.enable_ungrouped_vector_agg (default off).

Measured

Bench, 20M-row TSBS-cpu, q6 = SELECT count(*), avg(usage_system) FROM t WHERE usage_user > 90.0, serial, warm median of 5:

	ms
core Agg (GUC off)	16,244
batch fold (GUC on)	11,389

1.43x on the target query. The batch fold removes the per-row Datum, memory context, and executor tax that the #289 analysis measured as the gap. The remaining cost is the decode (bitunpack) plus serial execution; those are the next levers (word-parallel bitunpack, a parallel partial-aggregate path), each separately measurable. This does not close the whole 4x to TimescaleDB alone and does not claim to.

How (two commits)

1. The node (the ungrouped sibling of the grouped path Grouped vectorized aggregate (#289) #321 built): route a filtered or extended ungrouped aggregate to a dedicated single-pass scan node instead of core Agg. On its own this was a no-op (16.3 vs 16.4s) because for an ungrouped aggregate the per-row cost equals core Agg's; that measurement is the evidence that motivated step 2, and is kept as the foundation.
2. The batch fold: new reader accessors (ColumnarReadFoldNextGroup / ColumnarReadFoldGroupInfo / ColumnarReadFoldColumn) expose a loaded group's packed value streams. The node walks them column-at-a-time, evaluates a pushable WHERE inline (a btree compare per element, using PostgreSQL's float total order so NaN matches the operator ExecQual would call), and folds each surviving value through the same columnar_apply_one, in scan order, so the accumulators are byte-identical to the row path, floats included.

Eligible shapes: count(*), count(col), and sum/avg over int2/int4/float4/float8, with the whole WHERE expressible as btree keys on those types. Anything else (int8/numeric sum/avg, min/max, a residual or cross-type filter, or a group missing a column) falls back to the always-correct row path. The zone-map metadata path (count/min/max and sum/avg over int2/int4 with no filter) is untouched. With the GUC off, behavior is exactly as before. EXPLAIN reports Columnar Batch Fold: yes/no.

Tests and gate

test/ungrouped_vector_agg.sh (29 checks): on==off, bit-identical, across filtered and unfiltered float/int8/numeric sum/avg, min/max, nulls, an empty result, an all-null column, and after deletes. It also asserts via EXPLAIN that the batch path is taken for an eligible shape and the row path for min/max, so the A/B is never vacuous.

• Assert builds PG18 and PG19: this suite 29/29, and native_agg, native_groupagg, native_agg_deletes, native_agg_addcolumn, rewrite_group_scan unchanged.
• pg18_san (ASAN/UBSAN + alignment): clean. This is a decode-path change (typed reads over packed bytes), so the sanitizer run is the load-bearing safety check.

🤖 Generated with Claude Code

[ChronicallyJD]

Approving. I reproduced this independently on my own 4M-row TSBS-shaped fixture (not your bench), and it holds up: the fold is real, and it is correct.

Verified

	ms
fold OFF	1124
fold ON	834
heap	242

Columnar Batch Fold: yes confirmed firing via EXPLAIN. Results byte-identical across off / on / heap, including the float average: 400313|49.981327519677784 in all three. I get 1.27–1.35x rather than your 1.43x, which I read as fixture shape, not disagreement.

Credit where it is due on the writeup: reporting step 1 as a no-op ("16.3 vs 16.4s ... that measurement is the evidence that motivated step 2") is the right way to do this. So is "does not close the whole 4x to TimescaleDB alone and does not claim to." Neither was necessary to get the PR merged, and both make the result easier to trust.

One correction, and it is not a defect in this PR

The body says:

The remaining cost is the decode (bitunpack) plus serial execution; those are the next levers

That does not account for most of the residual, and I would not want it to send the next round of work at the wrong lever. With the fold ON my residual is flat in the number of aggregated columns (803 ms at 1 agg column, 837 ms at 5) and essentially unchanged with no filter at all (798 ms). Something that is neither decode-of-projected-columns nor filtering is dominating.

It is whole-table I/O. On a 12-column, 4M-row, 351 MB table (44,962 buffers total):

query	columns needed	buffers touched	% of table
count(*)	0	3	0%
sum(a)	1	45,094	100%
count(*), avg(b) WHERE a>90, fold ON	2	45,094	100%
count(*), avg(b) WHERE a>90, fold OFF	2	45,648	101%
sum of all 12	12	45,092	100%

One column costs the same bytes as twelve. Cross-checked against width: the identical 2-column query reads 7,620 buffers on a 2-column table (59 MB, 100%) and 45,097 on a 12-column one (351 MB, 100%) — in both cases exactly the whole relation.

This is pre-existing and not yours — fold OFF reads the same 100%, so the fold neither caused nor worsened it. The mechanism is columnar_native_load_group (src/columnar_reader.c:933), which does what its comment says and reads the group's bytes whole:

rs->nativeBuffer = palloc(rg->byteLength > 0 ? rg->byteLength : 1);
if (rg->byteLength > 0)
    ColumnarReadLogicalData(rs->rel, rg->fileOffset, rs->nativeBuffer, rg->byteLength);

projectedColumns is computed by the custom scan, passed down two call layers, copied into the read state at columnar_reader.c:334 — and then never read. The decode loop below it doesn't consult it either, so every column chunk is also decoded regardless of need.

So the accurate statement is that the next lever is projection, not bitunpack: word-parallel bitunpack would speed up decoding columns the query never asked for. I have filed this separately with the measurements rather than expanding your scope here.

Merging as-is.