Skip to content

feat: vortex-filecheck, FileCheck-style checks of Vortex encodings - #11544

Draft
joseph-isaacs wants to merge 2 commits into
ji/slt-tpch-fixture-namesfrom
ji/sleepy-albattani-o2d43n
Draft

joseph-isaacs wants to merge 2 commits into
ji/slt-tpch-fixture-namesfrom
ji/sleepy-albattani-o2d43n

Conversation

@joseph-isaacs

@joseph-isaacs joseph-isaacs commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds a FileCheck-style system for checking the array encoding trees of Vortex files, so tests can require specific encodings, or rule out bad ones, in generated files. A compressor change that re-encodes test or benchmark data then fails a check instead of only showing up as a benchmark swing.

This is the second PR in a stack:

  1. fix(sqllogictest): name TPC-H fixtures after their tables #11563 makes the TPC-H SLT fixtures actually run. This PR's check depends on it.
  2. This PR: the crate, vx filecheck, the SLT hook, and one check over a small TPC-H table.
  3. A follow-up adds the fuller TPC-H checks.

Changes

New vortex-filecheck crate

  • Renders each flat layout of a file as a text unit: a header line, then the array encoding tree. Rendering decodes the serialized array but decompresses nothing. Unit paths join layout child names: fields with ., chunks as [i], and other children (data, zones, values, codes) with /.
    unit: n_name/data rows=25 layouts=vortex.struct/vortex.zoned/vortex.flat
    root: vortex.fsst(utf8, len=25)
      uncompressed_lengths: vortex.primitive(u8, len=25)
      codes_offsets: vortex.primitive(u8, len=26)
    
  • Check files hold filecheck directives (check:, nextln:, not:, regex:, …), which match partially and in order. The crate adds two more:
    • files: <regex> names the Vortex files a check applies to, as a whole-path regex relative to the searched root.
    • units: <glob> checks the directives after it against every matching unit. A glob that matches no unit fails.
  • Parsing is strict. Every line must be blank, a # comment, or a directive at the start of the line. These are errors with a line number:
    • misspelled directives;
    • a missing space after the colon (filecheck would silently ignore check:foo);
    • empty patterns;
    • units: sections with no directives;
    • check files with no directives at all.
  • Failure reports name the failing directive and show the match trace around it. When a not: after the last positive match matches, filecheck itself reports nothing, so the report names those not: directives and shows the line that matched:
    FAIL line 7: units: n_*/data*: 4/5 failed
      unit n_regionkey/data/codes:
        failed: line 8: not: vortex.primitive
        > root: vortex.primitive(u16, len=25)
    
  • Entry points:
    • check_tree(session, root, check, …) checks every .vortex file under root that the check's files: regexes match, and fails if none match. It is meant for test suites, benchmark runners and data generators.
    • load_units + run_checks check a single file.
    • Path-based functions are compiled out on wasm32.
  • New dependency: filecheck 0.5. Its license (Apache-2.0 WITH LLVM-exception) is already allowed by deny.toml; it only depends on regex and thiserror, both already in the lockfile.

vx filecheck (vortex-tui)

  • vx filecheck <file> prints the dump, to help write checks. vx filecheck <file> <check> checks the file.
  • --exclude <glob> skips units without reading them. --metadata, --nbytes, --buffers and --stats add detail to the dump, and --explain prints the full match trace.

vortex-sqllogictest

  • Each .check file under slt/ becomes an slt::filecheck::* trial that runs check_tree rooted at slt/. It is ignored when its suite's generated data is absent, like the suite's .slt files.
  • Failures print a ready-to-run vx filecheck … --explain command for each failing file.
  • slt/tpch/filecheck/nation.check checks that data-gen writes TPC-H nation with:
    • a sequence-encoded key;
    • FSST names and comments;
    • a dictionary layout for the region key;
    • a zone map per column.

Testing

Check Result
cargo test -p vortex-filecheck 19 passed: parsing, malformed check files (8 cases), failure descriptions, whole-file and per-unit sections, excludes, check_tree file selection and errors
cargo clippy -p vortex-filecheck --all-targets --all-features -- -D warnings Clean
cargo +nightly-2026-11-13 fmt Applied
vx filecheck slt/tpch/data/nation.vortex slt/tpch/filecheck/nation.check All 5 sections pass on fresh data-gen output
cargo test -p vortex-sqllogictest Not run: the DuckDB source download is blocked in my environment
wasm32 check Not run: target not installed

API Changes

Additive only:

  • a new published crate, vortex-filecheck;
  • a new vx filecheck subcommand.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UeniBDxK1z3cP4gAzkh8c8

@joseph-isaacs joseph-isaacs changed the title feat(vx): FileCheck-style encoding checks for Vortex files feat: vortex-filecheck, FileCheck-style encoding checks for Vortex files Nov 17, 2026
@joseph-isaacs
joseph-isaacs force-pushed the ji/sleepy-albattani-o2d43n branch from 2f8e470 to e1f0da8 Compare November 17, 2026 20:04
joseph-isaacs and others added 2 commits November 17, 2026 20:09
Add a `vortex-filecheck` crate that renders each flat layout of a Vortex
file as a text unit (layout path header plus the array encoding tree,
decoded without decompressing) and checks it with `filecheck` crate
directives, which match partially and in order like LLVM FileCheck.

Check files add `files: <regex>` (the Vortex files they apply to,
relative to a searched root) and `units: <glob>` (check the following
directives against every matching unit). Parsing is strict: every line
must be blank, a `#` comment, or a directive at the start of the line,
so misspellings fail instead of silently never running, and a section
whose glob matches no unit fails. Failure reports name the directive
that missed, or the trailing `not:` directives that may have matched,
with the match trace around it.

`check_tree` checks every matching file under a root, for test suites,
benchmark runners and data generators. `vx filecheck <file> [<check>]`
prints a file's dump or checks it. The SLT runner turns each `.check`
file under `slt/` into an `slt::filecheck::*` trial rooted at `slt/`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UeniBDxK1z3cP4gAzkh8c8
Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk>
Check the encodings `data-gen` writes for TPC-H nation: a sequence
key, FSST names and comments, a dictionary layout for the region key,
and a zone map per column.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UeniBDxK1z3cP4gAzkh8c8
Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk>
@joseph-isaacs
joseph-isaacs force-pushed the ji/sleepy-albattani-o2d43n branch from e1f0da8 to 7fedfe6 Compare November 17, 2026 20:09
@joseph-isaacs joseph-isaacs changed the title feat: vortex-filecheck, FileCheck-style encoding checks for Vortex files feat: vortex-filecheck, FileCheck-style checks of Vortex encodings Nov 17, 2026
@joseph-isaacs
joseph-isaacs changed the base branch from develop to ji/slt-tpch-fixture-names November 17, 2026 20:10

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant