Make MultiFileFunction the default DuckDB scan path#7874
Draft
joseph-isaacs wants to merge 10 commits into
Draft
Make MultiFileFunction the default DuckDB scan path#7874joseph-isaacs wants to merge 10 commits into
joseph-isaacs wants to merge 10 commits into
Conversation
Per-column stats access by struct field name. Used by the upcoming MultiFileFunction-backed DuckDB scan, where DuckDB's BaseFileReader:: GetStatistics is keyed by name rather than index. Signed-off-by: Nicholas Gates <nick@spiraldb.com> Signed-off-by: Nicholas Gates <nick@nickgates.com>
…nction<OP>
Wraps DuckDB's templated MultiFileFunction machinery so an extension can
plug in a per-format reader and inherit cross-file orchestration (file
globbing, virtual columns, hive partitioning, COPY support) for free.
Layered:
- cpp/include/duckdb_vx/multi_file_function.h — C-ABI vtable
- cpp/multi_file_function.cpp — VortexMultiFileReaderInterface and
VortexFileReader subclass MultiFileReaderInterface and BaseFileReader,
forwarding virtual calls to the FFI vtable
- src/duckdb/multi_file_function.rs — Rust MultiFileFunction +
BaseFileReader traits with associated types (mirroring the existing
TableFunction shape) and a register_multi_file_function method on
DatabaseRef
This commit does not yet register a function — the next commit adds
VortexMultiFileFunction and wires it up.
Signed-off-by: Nicholas Gates <nick@spiraldb.com>
Signed-off-by: Nicholas Gates <nick@nickgates.com>
Concrete MultiFileFunction implementation that drives a per-file scan via
VortexFile directly (rather than going through MultiLayoutDataSource),
making file-level statistics, dtype, and pruning available without
LayoutReader downcasts.
Registration:
- read_vortex_v2 is always registered for direct comparison.
- VX_DUCKDB_MULTI_FILE_FUNCTION=1 swaps read_vortex / vortex_scan over to
the v2 path so existing benchmarks and SQL can run unchanged.
Smoke tests cover single-file, strings, and multi-file glob.
Known v2 gaps vs the existing TableFunction-backed scan (documented on
use_multi_file_function): no projection or filter pushdown; no Vortex
filesystem integration; no list-of-paths overload; no union_by_name. The
v2 path is intended for benchmarking the orchestration layer first;
parity work is follow-up.
Signed-off-by: Nicholas Gates <nick@spiraldb.com>
Signed-off-by: Nicholas Gates <nick@nickgates.com>
Brings the MultiFileFunction-backed scan up to feature parity with the
existing TableFunction path on the test suite (189/189 pass under both
when VX_DUCKDB_MULTI_FILE_FUNCTION=1).
FFI surface additions on the multi-file vtable:
- prepare_reader(reader, projection, filters): called once after
create_reader, hands the per-file reader the columns DuckDB wants
(in chunk order) plus the pushed-down TableFilterSet.
- cardinality(bind_data, file_count): row-count estimate for the
optimizer; falls back to DuckDB's default when not provided.
- to_string(bind_data, map): bind-time EXPLAIN key/value output.
C++ adapter overrides BaseFileReader::PrepareReader to translate
column_ids -> projected column names and forward filters; overrides
MultiFileReaderInterface::GetCardinality and TableFunction::to_string
to delegate to the new FFI callbacks.
In the Rust trait MultiFileFunction picks up `cardinality` and
`to_string` defaults; BaseFileReader picks up `prepare_reader` with a
default no-op so existing impls don't break.
VortexMultiFileFunction wires it together:
- projection: builds a `select(names, root())` Vortex projection so
chunks contain exactly the columns DuckDB expects (also handles
SELECT count(*) which is the explicit zero-projection case).
- filter: converts each TableFilter via try_from_table_filter and
AND-collects into the scan filter.
- file-level pruning: VortexFile::can_prune against the combined
filter; pruned files short-circuit TryInitializeScan with false.
- progress: rows_scanned / file.row_count() in [0, 100].
- cardinality: rough APPROX_ROWS_PER_FILE * file_count estimate
(bind_data can't be mutated from bind_reader through the current
FFI; better numbers wait on that hop being added).
- to_string: emits a "Function" row.
Multi-file orchestration:
- register through MultiFileReader::CreateFunctionSet so the function
set includes both the single-VARCHAR and LIST(VARCHAR) overloads.
`read_vortex_v2(['a.vortex','b.vortex'])` works.
- file IO routes through resolve_filesystem(base_url, ctx), so the
`vortex_filesystem` extension option ('vortex' vs 'duckdb') chooses
the same backends as the v1 path. HTTP/S3 work via DuckDB's httpfs
when 'duckdb' is selected.
Late materialization remains intentionally off until the per-file
reader supports AddVirtualColumn for file_index / file_row_number;
batch parallelism within a file is also a follow-up (TryInitializeScan
is still one-shot per reader).
Signed-off-by: Nicholas Gates <nick@spiraldb.com>
Signed-off-by: Nicholas Gates <nick@nickgates.com>
Flip the VX_DUCKDB_MULTI_FILE_FUNCTION toggle so the new MultiFileFunction-backed read_vortex is used by default. The legacy TableFunction path can still be selected by setting the env var to 0. This enables CI benchmarks to exercise the multifile read path without requiring explicit env var configuration. Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk>
Merging this PR will degrade performance by 94.59%
|
| Mode | Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|---|
| ❌ | Simulation | chunked_bool_canonical_into[(1000, 10)] |
46.2 µs | 57.1 µs | -18.98% |
| ❌ | Simulation | chunked_constant_i32_append_to_builder[(1000, 10)] |
30.5 µs | 40.7 µs | -25.2% |
| ❌ | Simulation | varbinview_large |
174.5 µs | 435.7 µs | -59.95% |
| ⚡ | Simulation | new_alp_prim_test_between[f64, 32768] |
237.5 µs | 192.4 µs | +23.4% |
| ❌ | Simulation | new_bp_prim_test_between[i16, 32768] |
120.7 µs | 134.3 µs | -10.13% |
| ❌ | Simulation | new_bp_prim_test_between[i32, 16384] |
95 µs | 108.3 µs | -12.26% |
| ❌ | Simulation | new_bp_prim_test_between[i32, 32768] |
141.3 µs | 169.1 µs | -16.42% |
| ❌ | Simulation | new_bp_prim_test_between[i64, 16384] |
115.5 µs | 143.8 µs | -19.65% |
| ⚡ | Simulation | take_10_stratified |
26.5 µs | 23.9 µs | +11.11% |
| ❌ | Simulation | new_bp_prim_test_between[i64, 32768] |
178.4 µs | 236.6 µs | -24.6% |
| ❌ | Simulation | decompress_rd[f32, (100000, 0.01)] |
412.7 µs | 495.9 µs | -16.76% |
| ❌ | Simulation | decompress_rd[f32, (100000, 0.1)] |
412.8 µs | 495.9 µs | -16.77% |
| ❌ | Simulation | decompress_rd[f64, (100000, 0.01)] |
668.4 µs | 843.3 µs | -20.74% |
| ❌ | Simulation | decompress_rd[f64, (100000, 0.1)] |
668.4 µs | 843.3 µs | -20.74% |
| ⚡ | Simulation | decompress[u32, (1000, 256)] |
19.3 µs | 17.5 µs | +10.18% |
| ⚡ | Simulation | decompress[u64, (1000, 256)] |
20.8 µs | 18.9 µs | +10.04% |
| ⚡ | Simulation | decompress[u16, (1000, 256)] |
18.8 µs | 16.9 µs | +10.93% |
| ❌ | Simulation | null_count_run_end[(10000, 1024, 0.01)] |
3.4 µs | 4.1 µs | -16.28% |
| ❌ | Simulation | null_count_run_end[(10000, 256, 0.01)] |
3.4 µs | 4.1 µs | -16.28% |
| ❌ | Simulation | null_count_run_end[(100000, 1024, 0.01)] |
3.4 µs | 4.1 µs | -16.28% |
| ... | ... | ... | ... | ... | ... |
ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.
Comparing ji/multifile-default (a8598ef) with ngates/duckdb-multi (54e8da0)
Footnotes
-
2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
joseph-isaacs
added
the
action/benchmark
joseph-isaacs
added
action/benchmark
github-actions
Bot
removed
the
action/benchmark
Contributor
Polar Signals Profiling ResultsLatest Run
Powered by Polar Signals Cloud |
Contributor
Polar Signals Profiling ResultsLatest Run
Powered by Polar Signals Cloud |
Contributor
Polar Signals Profiling ResultsLatest Run
Powered by Polar Signals Cloud |
Contributor
Benchmarks: PolarSignals ProfilingVortex (geomean): 0.954x ➖ datafusion / vortex-file-compressed (0.954x ➖, 2↑ 0↓)
|
Contributor
File Sizes: PolarSignals ProfilingNo file size changes detected. |
Contributor
Benchmarks: FineWeb NVMeVerdict: No clear signal (low confidence) datafusion / vortex-file-compressed (0.976x ➖, 0↑ 0↓)
datafusion / vortex-compact (1.012x ➖, 0↑ 0↓)
datafusion / parquet (1.001x ➖, 0↑ 0↓)
duckdb / vortex-file-compressed (0.916x ➖, 1↑ 0↓)
duckdb / vortex-compact (0.966x ➖, 2↑ 1↓)
duckdb / parquet (1.006x ➖, 0↑ 1↓)
Full attributed analysis
|
Contributor
File Sizes: FineWeb NVMeNo file size changes detected. |
Contributor
Benchmarks: TPC-H SF=1 on NVMEVerdict: No clear signal (low confidence) datafusion / vortex-file-compressed (0.982x ➖, 0↑ 0↓)
datafusion / vortex-compact (0.984x ➖, 0↑ 0↓)
datafusion / parquet (0.981x ➖, 2↑ 1↓)
datafusion / arrow (0.979x ➖, 0↑ 1↓)
duckdb / vortex-file-compressed (0.941x ➖, 5↑ 0↓)
duckdb / vortex-compact (0.919x ➖, 8↑ 0↓)
duckdb / parquet (0.996x ➖, 0↑ 0↓)
duckdb / duckdb (0.970x ➖, 0↑ 0↓)
Full attributed analysis
|
Contributor
File Sizes: TPC-H SF=1 on NVMENo file size changes detected. |
Contributor
Benchmarks: TPC-DS SF=1 on NVMEVerdict: No clear signal (low confidence) datafusion / vortex-file-compressed (1.101x ❌, 1↑ 51↓)
datafusion / vortex-compact (1.083x ➖, 0↑ 32↓)
datafusion / parquet (1.091x ➖, 1↑ 44↓)
duckdb / vortex-file-compressed (1.028x ➖, 7↑ 16↓)
duckdb / vortex-compact (1.017x ➖, 9↑ 15↓)
duckdb / parquet (1.057x ➖, 1↑ 18↓)
duckdb / duckdb (1.034x ➖, 0↑ 10↓)
Full attributed analysis
|
Contributor
File Sizes: TPC-DS SF=1 on NVMENo file size changes detected. |
Contributor
Benchmarks: FineWeb S3Verdict: No clear signal (low confidence) datafusion / vortex-file-compressed (1.075x ➖, 0↑ 0↓)
datafusion / vortex-compact (1.038x ➖, 0↑ 0↓)
datafusion / parquet (1.065x ➖, 0↑ 0↓)
duckdb / vortex-file-compressed (1.263x ➖, 0↑ 2↓)
duckdb / vortex-compact (1.262x ➖, 0↑ 3↓)
duckdb / parquet (1.081x ➖, 0↑ 0↓)
Full attributed analysis
|
Contributor
Benchmarks: Statistical and Population GeneticsVerdict: Likely regression (low confidence) duckdb / vortex-file-compressed (1.259x ❌, 0↑ 4↓)
duckdb / vortex-compact (1.096x ➖, 0↑ 2↓)
duckdb / parquet (1.026x ➖, 0↑ 0↓)
Full attributed analysis
|
Contributor
File Sizes: Statistical and Population GeneticsNo file size changes detected. |
Contributor
Benchmarks: TPC-H SF=10 on NVMEVerdict: No clear signal (low confidence) datafusion / vortex-file-compressed (1.014x ➖, 0↑ 0↓)
datafusion / vortex-compact (1.013x ➖, 0↑ 0↓)
datafusion / parquet (1.011x ➖, 0↑ 0↓)
datafusion / arrow (0.987x ➖, 1↑ 0↓)
duckdb / vortex-file-compressed (0.991x ➖, 2↑ 1↓)
duckdb / vortex-compact (0.962x ➖, 5↑ 2↓)
duckdb / parquet (0.996x ➖, 0↑ 0↓)
duckdb / duckdb (0.997x ➖, 0↑ 0↓)
Full attributed analysis
|
Contributor
File Sizes: TPC-H SF=10 on NVMENo file size changes detected. |
Contributor
Benchmarks: Clickbench on NVMEVerdict: No clear signal (low confidence) datafusion / vortex-file-compressed (1.043x ➖, 0↑ 2↓)
datafusion / parquet (1.028x ➖, 0↑ 0↓)
duckdb / vortex-file-compressed (1.193x ❌, 1↑ 23↓)
duckdb / parquet (1.008x ➖, 0↑ 0↓)
duckdb / duckdb (1.005x ➖, 1↑ 0↓)
Full attributed analysis
|
Contributor
File Sizes: Clickbench on NVMEFile Size Changes (1 files changed, -0.0% overall, 0↑ 1↓)
Totals:
|
Contributor
Benchmarks: Random AccessVortex (geomean): 0.995x ➖ unknown / unknown (1.014x ➖, 0↑ 1↓)
|
Contributor
🚨🚨🚨❌❌❌ SQL BENCHMARK FAILED ❌❌❌🚨🚨🚨Benchmark |
Contributor
Benchmarks: CompressionVortex (geomean): 1.009x ➖ unknown / unknown (0.995x ➖, 3↑ 3↓)
|
Contributor
Benchmarks: TPC-H SF=10 on S3Verdict: No clear signal (environment too noisy confidence) datafusion / vortex-file-compressed (1.048x ➖, 0↑ 0↓)
datafusion / vortex-compact (1.131x ➖, 0↑ 2↓)
datafusion / parquet (1.067x ➖, 0↑ 0↓)
duckdb / vortex-file-compressed (1.412x ❌, 0↑ 17↓)
duckdb / vortex-compact (1.411x ❌, 0↑ 16↓)
duckdb / parquet (1.054x ➖, 0↑ 0↓)
Full attributed analysis
|
joseph-isaacs
added
the
action/benchmark
github-actions
Bot
removed
the
action/benchmark
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
VX_DUCKDB_MULTI_FILE_FUNCTIONtoggle so the newMultiFileFunction-backedread_vortex/vortex_scanis used by defaultTableFunctionpath can still be selected by settingVX_DUCKDB_MULTI_FILE_FUNCTION=0Test plan
cargo build -p vortex-duckdbpasses🤖 Generated with Claude Code