Skip join key null-checks on columns known null-free

[vbmithr]

Summary

ray_vec_is_null is 13.28% of samples in a profile of our service, called
from the join build and probe paths (join_count_fn, join_fill_fn) — every
key column of every row is tested for null on every join.

The engine already tracks whether a column has nulls: the index routing table
disqualifies .idx.hash on HAS_NULLS columns and falls back to a scan, so
the flag is consulted elsewhere. The join path appears not to consult it.

What we are asking for

When a join key column's HAS_NULLS flag is clear, skip the per-element null
test in the join's build and probe loops. No new API, no new attribute — the
information is already there, and 13% of our CPU is spent rediscovering it one
element at a time.

If the flag is not maintained precisely enough to be trusted at that site, the
alternative is an explicit column attribute (.attr.set 'not-null) that a
caller can assert, with the usual fallback contract.

Context

Our join keys are venue and instrument symbol columns on a market-data
book table. They are structurally never null — a row without an instrument
could not have been ingested — but there is no way to say so, and no way to
stop paying for the check.

This is the cheapest of the three requests we are opening; the other two are
the join sites in the index routing table, and a join form that returns a row
selection instead of a materialised table.

---

Measured on rayforce 2.6.2 (the build carrying bc350ddc).

[singaraiona]

Fixed in #598. Thanks for the profile — the cost is real and it was worse than the line you saw suggests. One correction first, because it matters for the request itself.

The HAS_NULLS gate would have been a no-op for your columns

ray_vec_is_null returns for SYM and STR before it ever consults HAS_NULLS (vec.c:1601-1605). Text nulls are canonical empty payloads — SYM null is id 0, STR null is length 0 — and the flag is deliberately not trusted for them, so that old persisted columns and raw gathers observe the same semantics. That is also why ray_vec_may_have_nulls returns true unconditionally for SYM/STR.

Your keys are venue and instrument, both SYM. Gating the join on HAS_NULLS would have changed nothing for them. The information genuinely was not "already there" in the form you expected — for text columns the payload is the only source of truth, so proving a column null-free means scanning it.

What we did instead

One proof per join, over every key column on both sides, computed once and threaded into the build and probe loops so the per-cell call disappears:

• text columns are proven by the chunked, vectorized zero-scan added in SYM filters scan the whole column for nulls on every query (expr_compile → ray_vec_has_nulls) #533 — O(n) once, with an early exit;
• everything else reads the flag, and a set bit is taken at face value, so the proof never degrades into a per-element walk;
• flag-readable columns are settled first, so a nullable numeric key short-circuits before any text column is scanned.

The larger find was elsewhere. The #458 null-run pre-scan gates on ray_vec_may_have_nulls, which as above is unconditionally true for SYM/STR — so your SYM-keyed join was also running a full per-key-per-build-row ray_vec_is_null scan before the join proper, on every single execution, on top of the build and probe cost. A proven null-free key set cannot contain an all-null row, so that scan is now skipped entirely. That is plausibly the bigger half of your 13.28%.

Numbers

Release build, 1:1 book join (4M probe x 500K build), against the null-aware loops forced on in the same binary:

case	baseline	with proof	median / min
two SYM keys	275.2 ms	248.9 ms	-9.5% / -7.8%
single I64 key	106.1 ms	99.4 ms	-6.3% / -7.9%

Set your expectations against that rather than against the 13.28%: that figure is samples in ray_vec_is_null across all its callers, and our benchmark is pure join work where your service is not. If your join keys are ever genuinely nullable SYM/STR, note there is a small cost in the other direction — a proof that fails scans part of the column (~8 ms on 4M rows) and gains nothing. Numeric keys never pay it.

On .attr.set 'not-null

We are not adding it. A not-null attribute a caller can assert turns a slow join into a silently wrong one the first time the assertion is mistaken — and "a row without an instrument could not have been ingested" is exactly the kind of invariant that holds until some backfill or replay path violates it. The payload scan costs ~8 ms and cannot be wrong. If you later hit a case where even that is too much, #595 is the right lever: a maintained index on the key column would let the join skip the scan on evidence rather than on assertion.

Worth a look when you pick up the build: if the scan ever does show up for you, it will be on a column you believe is null-free but which the scan disagrees about — and that would be worth knowing about for its own sake.