Skip to content

fix(device): NULL vector elements stay on the host, and Float64 filters compare as DataFusion 55 does (#105, #28) - #151

Merged
vyncint merged 4 commits into
mainfrom
pr/030-device-port
Nov 18, 2026
Merged

vyncint merged 4 commits into
mainfrom
pr/030-device-port

Conversation

@vyncint

@vyncint vyncint commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Two device-correctness fixes from the 0.3.0 review, one commit each, with the evidence in each commit body. Both are ported onto the join rewrite (#140).

  • NULL elements inside a vector column become valid 0.0 on the device filter and join paths #105 The device transfer format has one validity bit per row and dropped a vector column's own bitmap. So a NULL element inside a valid vector row came back from a CUDA or Metal filter, or a CUDA join, as a valid 0.0.
    • columns::extract now refuses such a column (device.vector_null_element).
    • The operator layer keeps the column on the host and gathers it at the device's row ids, as it already does for Utf8. The filter or join itself still runs on the device.
    • Vector distance, whose kernel must read the column, runs that batch on the CPU reference and counts it.
    • A join's build side is checked once per operator, not once per probe batch, so the build is still uploaded and indexed once (Persist the CUDA join table across probe batches and size group tables by distinct keys #45).
  • Match Arrow totalOrder float comparison in the CUDA filter kernel and add NaN and -0.0 rows to conformance #28 The GPU filter now compares Float64 in DataFusion 55's order: -0.0 reads as +0.0, then IEEE totalOrder (a NaN above +inf). Before, filter_project.cu used plain IEEE </==, so v > 4.0 never selected a NaN. The CPU reference applied totalOrder without the zero step, so every GPU-targeted Float64 filter that ran on the reference returned other rows than --target cpu over -0.0. That was a regression from the DataFusion 55 bump.
    • The issue asked for pure totalOrder, written against DataFusion 54. Placement must never change a query's result, so the device follows DataFusion 55. The commit body cites the DataFusion source lines.
    • oxide gen-data --special-floats writes a table holding NaN of each sign, ±inf, ±0.0 and subnormals. The conformance and CLI suites filter it on every target.

Verified on a Tesla T4 (driver 595.71.05, CUDA 13.2, compute capability 7.5, 2026-11-18), on the fix branch these commits come from:

  • conformance with OXIDE_BACKEND=cuda: 4 passed (special_floats, vector_null_elements, gpu_backend_matches_datafusion_when_available, gpu_aggregate_edges_match_the_reference_when_available)
  • device suite: 43 passed
  • cli special_floats_filter_alike_on_every_target: 1 passed, where --target cuda runs the kernel
  • the embedded GPU-target suite: 4 passed

Closes #105
Closes #28

The device transfer format (columns::extract / rebuild) has one validity
bit per row and drops a FixedSizeList child's own bitmap, so a NULL
element inside a valid vector row came back from a CUDA or Metal filter,
or a CUDA join, as a valid 0.0. The CPU backend never moves bytes, and
the conformance fixture's vector child is non-nullable, so nothing saw
it.

- columns::row_with_null_element(array) finds the first valid row that
  holds a NULL element. NULL elements under a NULL row do not count:
  append_null leaves exactly those, and counting them would keep every
  nullable vector column off the device. It counts them with a popcount
  per NULL row, so the common nullable column does not pay a walk over
  every element on every upload; only a column that has such a row is
  walked, to name it.
- extract refuses such a column (Unsupported,
  "device.vector_null_element"), so no path can round-trip it into
  numbers.
- The operator layer keeps such a projected column on the host and
  gathers it at the device's row ids, as it already does a Utf8 column;
  the filter or join itself still runs on the device. Vector distance,
  whose kernel has to read the column, runs that batch on the CPU
  reference, counted, with the same distances: the CPU kernel, the UDF
  and the device all read the bytes under the NULL.

This is 11b143f (fix/030-device, on 08a9147) ported onto the join
rewrite (#45, b04155e here), where a join is planned by a JoinPlan per
probe batch and its build side is uploaded and indexed once per
operator:
- JoinPlan::new takes the probe batch and the JoinBuild instead of two
  schemas, and side_plan takes a per-column answer to "does it travel".
- The probe batch is checked per batch, as a filter's batch is.
- The build side is checked once, in JoinBuild::new, and kept as a flag
  per column. Since #45 its device copy serves every probe batch, so
  checking it per probe batch would put back per-batch build-side work
  (for a nullable vector column, a pass over its rows) that #45 took
  out. Its plan is then the same for every batch, so the cached device
  build is still reused.
- In the conformance suite, TransferSim also implements
  prepare_join_build and probe_join (the CPU backend's, on batches that
  went through the format), and join_once drains the output in pieces of
  61 rows (#95), so a column kept on the host is gathered at each
  piece's row ids.

The WIP I inherited refused the column in extract only, which sent the
whole batch to the CPU: the all-or-nothing eligibility the 2026-09-02
audit (P2) removed for Utf8 columns. The issue names keeping such
columns on the host as a fix, and it keeps the device path. Not done:
carrying element validity through the device gathers, which would need
the CUDA gather kernels and the Metal kernels (not compilable here) to
move element bits; the extract/rebuild round trip therefore refuses
such a column rather than carrying it.

Tests:
- conformance, vector_null_elements: TransferSim is a CUDA-claiming
  backend whose upload and download go through
  columns::extract_batch / rebuild_batch, what CudaBackend and
  MetalBackend do around their copies, with the CPU kernels in between.
  gen_null_elements has a nullable child, NULL elements under every
  NULL row and, with holes, one in about one valid row in five. Filter
  and join (the vector column on the probe side, then the build side)
  against stock DataFusion over SEEDS x SIZES; then the witness, with
  and without holes: the filter and both joins count no fallback and
  upload bytes, and vector distance falls back exactly when there are
  holes, with the CPU's distances.
  - before (this tree's operator.rs planning and an extract without the
    refusal, i.e. what d521037 does): red at the first filter check,
    `0|[4.797393, 3.2308922, 0.0, 1.423552]` where DataFusion has
    `0|[4.797393, 3.2308922, NULL, 1.423552]`.
  - after: green, with the rest of the suite (9 passed, 3 ignored).
- columns unit tests: a NULL element in a valid row is refused naming
  the row; NULL elements under NULL rows round-trip equal; only the
  extracted rows of a slice count; the check finds a NULL element when
  the counts match but the positions do not; a list offset reaches it
  through its parts (arrow-rs lists always present offset 0). 10 pass;
  columns.rs is 11b143f's unchanged, so its counts-only guard check there
  holds as recorded.
- operator unit test: JoinPlan keeps such a column off the device and
  asks for row ids on either side, the probe side checked from the
  batch and the build side from its JoinBuild; the same column with
  NULLs only under its NULL row is uploaded.

Guard checks, each restored after:
- travels() by type alone: the witness red, "filter fell back (holes:
  true)", and the operator test red (the probe side uploaded [0, 1]).
- the build side's flags by type alone (JoinBuild::new): the witness
  red, "build-side join fell back (holes: true)", and the operator test
  red at its third case (the build side uploaded [0, 1]).
- extract without the refusal: the witness red, "vector distance
  (holes: true)" with 0 fallbacks where 1 is expected.

On a device, gpu_backend_keeps_null_vector_elements_when_available
(--ignored) runs the same checks, skipping the join witness where the
backend declines joins (Metal). It has not run on a device yet:
  OXIDE_BACKEND=cuda cargo test -p oxidelake-compute --features cuda \
    --test conformance -- --ignored vector_null_elements

Closes #105

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
DataFusion orders floats by IEEE totalOrder (a NaN above +inf, one with
its sign bit set below -inf) and, since 55, reads -0.0 as +0.0 on both
sides of a comparison first: datafusion-physical-expr-common 55.2.0
src/datum.rs:88-94, where apply_cmp passes both operands through
normalize_float_zero (datafusion-common 55.2.0 src/utils/mod.rs:1396)
before Arrow's cmp kernels. 54.1.0's datum.rs has no such step. Neither
GPU-placed path matched it:

- filter_project.cu compared doubles with plain IEEE `<`/`==`, where any
  comparison with a NaN is false: `v > 4.0` never selected a NaN.
- the CPU reference (cpu/kernels.rs evaluate_predicate) called Arrow's
  totalOrder kernels as they are, so `-0.0 = 0.0` was false and
  `-0.0 < 0.0` true there. On 08a9147 every GPU-targeted Float64 filter
  that ran on the reference (every Float64 predicate on Metal, a GPU
  target on a machine without that GPU, a per-batch fallback) returned
  other rows than --target cpu over -0.0: a regression from the
  DataFusion 55 bump in the CPU reference, unseen because no fixture
  held a -0.0. On a CUDA device the kernel's plain IEEE comparison
  happened to agree on zeros.

The reference now reads -0.0 as +0.0 in the column (copied only when it
holds one, as DataFusion does) and in the literal. The kernel compares
sign-adjusted bit patterns, the transform f64::total_cmp applies, with
-0.0 given +0.0's key.

Decision, agreed with the lead: placement must never change a query's
result, so the device filter and its CPU reference follow DataFusion
55: -0.0 compares as +0.0, then totalOrder. The issue asks for Arrow's
totalOrder, and its 2026-11-11 comment says "-0.0 < 0.0"; both were
written against DataFusion 54, where that was stock DataFusion's order.
The WIP I inherited compared in pure totalOrder on the device, which
would have broken zeros on CUDA as well.

Tests:
- cpu::kernels float_comparisons_order_as_datafusion_does: NaN of each
  sign, both infinities and both zeros against literals.
- conformance, special_floats: v drawn from all six special values (NaN,
  -NaN, +-inf, +-0.0), the two subnormals nearest zero and ordinary
  values; 12 predicates (SQL and the plan's Predicate; literals include
  -0.0, NaN and +-inf) over SEEDS x SIZES on the CPU backend. Stock
  DataFusion's rows must equal GpuFilterExec's, and equal the order
  written out by hand from f64::total_cmp, so a DataFusion that moves
  the order again fails naming DataFusion. Not added to gen_left: its v
  feeds the aggregate check too, and MIN/MAX over NaN and signed zeros
  is #101's.
- cli: gen-data --special-floats read back with the parquet crate (all
  six values present); four filters planned as GpuFilterExec[cuda]
  print the same CSV as --target cpu.
- datagen: the default table pinned by a content digest; the special
  table equals it except v on every 16th row.

Before (reference as at 08a9147, rest of this change applied):
conformance red at `v < 0.0` seed=1 rows=64 (the reference selected the
-0.0 rows r30, r47, r59, r60, r61, r6, DataFusion did not); cli red at
`v < 0.0` (--target cuda printed ids 16, 112, ... holding -0.0,
--target cpu did not). After: green; conformance 8 passed, 3 ignored;
make test green. (Numbers from fix/030-device; on this tree see below.)

Guard checks, each restored after:
- no column normalization: unit red (`v = 0.0` -> [4], want [4, 5]),
  conformance red at `v < 0.0`, cli red.
- no literal normalization: unit red (`v = -0.0` -> []), conformance
  red at `v > -0.0`, cli red at `v <= -0.0`.
- gen-data replacing the PRNG draw instead of overwriting after it:
  special_floats_overlay_the_default_table red ("column 1").

The kernel cannot run here (no GPU, no NVRTC). As a check of its logic
only, a throwaway test compiled filter_project.cu as host C++ (g++,
shims for __double_as_longlong and the thread indices), ran
oxide_compare_f64 over 16 values (the 12 above, a NaN payload of each
sign, +-f64::MAX) x the same 16 literals x 5 ops, and compared every
mask with evaluate_predicate: 80 of 80 agree; filter_project.cu at
08a9147 disagrees on 66 of 80. Not committed. For the T4:
  OXIDE_BACKEND=cuda cargo test -p oxidelake-compute --features cuda \
    --test conformance -- --ignored special_floats
  cargo test -p oxidelake-runtime --features cuda --test cli \
    special_floats

New (oxidelake-storage, datagen feature): DemoOptions,
write_demo_table_with, demo_batches_with, demo_chunks_with,
SPECIAL_FLOATS, SPECIAL_FLOAT_EVERY; `oxide gen-data --special-floats`.
The default table is unchanged: the generator at 08a9147, compiled
beside this one in a throwaway test, gives equal batches for 66536 rows
seed 42, 1 row seed 7 and 200000 rows seed 3, and the pinned digest is
its own.

This is c4c185b (fix/030-device, on 08a9147) on the integration tree,
after the #105 port it builds on (its special_floats module reuses
vector_null_elements::filter_once). The change is the same; conflicts
were only beside other fixes' text: kernels.rs's arrow imports (#95's
TakeOptions), the SPEC's operator list and STATUS's CUDA row (#45's
join), and the end of tests/cli.rs (#92's cluster tests). Re-run here:
conformance 10 passed, 4 ignored; cli special_floats green; the unit
test green beside #101's total_order_keys test; datagen 4 passed.
Before (the reference as at 08a9147, rest of this change applied):
conformance red at `v < 0.0` seed=1 rows=64, cli red at `v < 0.0`, as
on fix/030-device. Note for #101 (fx3-agg is checking it against
DataFusion 55): the reference now compares filters with -0.0 = +0.0,
while #101's MIN/MAX orders -0.0 below 0.0; the module doc says both.

Refs #28

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
@vyncint vyncint added this to the v0.3.0 milestone Nov 18, 2026
vyncint added a commit that referenced this pull request Nov 18, 2026
Release, CI, dashboard and docs fixes from the 0.3.0 review, one commit each, with the before/after evidence in each commit body.

**Release and CI**
- **#130** `release.yml` treated any crates.io answer other than 200 (a 429, a 503) as "first release, no baseline" and skipped `cargo-semver-checks` before publishing. The job now confirms the baseline with `.github/scripts/crates-io-baseline.sh`: a 429 or 5xx is retried and then fails, and a 404 fails at once. It is never skipped.
- **#131** A `binaries.yml` re-run skipped any target whose archive was attached, even when its checksum or alias was missing, so the formula job then failed for good. A partly attached target is now completed from the attached archive without a rebuild, and a checksum with no archive stops the job.
- **#127** The CI msrv job installed 1.94.1 but compiled with the 1.98.0 that `rust-toolchain.toml` pins, so it could not fail on an MSRV break. It now compiles with the declared version and asserts which compiler ran.
- **#128** The `metrics` feature's binaries were compiled by no gate step: rustdoc does not type-check function bodies. `make lint-metrics` and `make test-metrics` are now in `make gate` and in CI, with a check that every runtime feature is compiled by some CI target.
- **Refs #38** `gpu.yml` is an on-demand, dispatch-only workflow that runs the new `make test-cuda-device` on a self-hosted runner labelled `gpu`. It has never run, because no such runner is registered. #38 stays open until it runs green on a CUDA machine. `docs/RELEASING.md` step 0 says what a release states in the meantime. The target's three commands are the ones that passed on a Tesla T4 today (#139–#151).

**Dashboard and TUI**
- **#120** `oxide tui --table Trips=PATH` died after the query ran: the table is registered under its folded name and was profiled under the quoted one.
- **#121** Min/max were profiled only for Int64, Float64 and Utf8, so the demo table's own Parquet strings (Utf8View in DataFusion 55) showed empty min/max. Every type DataFusion can order is now profiled.
- **#123** The Inspector summed the counters of every operator sharing a name, as with a self-join's two filters. Each `Gpu*Exec` now reads its own counters back (`operator_stats()`).
- **#126** A refresh that supplies or grows the plan left the selection bounded by the old plan's length.
- **#122** The Describe panel cut numbers to fit without any mark, so 76923 nulls were drawn as 769 at 80x24. Numbers are now never cut: the layout gives the panel its width, and the snapshots changed accordingly.

**Docs**
- **#129** crates.io resolves a README's relative links against each crate's directory, so all 33 were 404s on all nine crate pages. Every link is now absolute, and `make crate-metadata` refuses a relative one. This branch also fixes the one relative link that #147 added.
- **#132** The spill manager, the CUDA record and the api crate are now described as built: no watermarks, no background demotion, no throughput metric.

Two commits come from rebasing onto `main`. One makes the README's new `SECURITY.md` link absolute, which the new gate caught. The other pins `gpu.yml`'s checkout comment to `v7.0.1`, as #138 did for every other workflow.

Locally on this branch: fmt, the TUI suites, the operator-stats test, the runtime library tests, metrics clippy, workspace clippy, `crate-metadata`, `release-scripts`, `ci-scripts` (47 tests) and zizmor all pass.

Closes #130
Closes #131
Closes #127
Closes #128
Closes #120
Closes #121
Closes #123
Closes #126
Closes #122
Closes #129
Closes #132

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>

# Conflicts:
#	STATUS.md
#	crates/oxidelake-device/src/cpu/kernels.rs
#	crates/oxidelake-storage/src/datagen.rs
Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
@vyncint
vyncint merged commit 7299a22 into main Nov 18, 2026
19 checks passed
@vyncint
vyncint deleted the pr/030-device-port branch November 18, 2026 10:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant