Repository navigation
Documentation: README, file format spec and a query walkthrough - #6
Merged
Merged
Conversation
The README covers what each layer does and, more usefully, why the awkward decisions went the way they did — why folding stops at division by zero, why a predicate is never pushed into the padded side of an outer join, why join reordering prefers a connected relation over a smaller one. It also says plainly what is not supported, and records the three bugs I actually hit. docs/file-format.md specifies .qfc byte by byte: the footer, the zone maps, the three encodings and the rules for choosing between them, and every corrupt-input case the reader rejects. docs/query-lifecycle.md follows one query through lexing, parsing, binding, optimising, physical planning and execution, with real plan output at each step.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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
1 participant
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.
Three documents.
README — what the engine is, how to run it, what it supports and what it does not. The parts worth reading are not the feature list but the justifications: why constant folding deliberately stops at division by zero and integer overflow, why a predicate is never pushed into the padded side of an outer join, why join reordering prefers a connected relation over a smaller unrelated one, and why the type system is four types wide. It carries the benchmark table, the real
EXPLAIN/EXPLAIN ANALYZEoutput, and a "Things I got wrong" section recording the three bugs I actually hit — including the one the 43 end-to-end tests missed.It also says plainly what is not there: no subqueries, CTEs, window functions,
UNION,UPDATE/DELETE, transactions, indexes or concurrency. Better said up front than discovered.docs/file-format.md —
.qfcbyte by byte. The footer layout and why it lives at the end, the zone-map structure, the exact pruning rule per operator (including why<>only prunes a constant group, and why a conjunction prunes when either half rules a group out while a disjunction needs both), the three encodings, and the measured signals that choose between them. Every corrupt-input case the reader rejects is listed, because a truncated file is an expected failure mode rather than a bug.It is also honest about the one statistic that is not exact: merged
distinct_countis an upper bound, since row groups can hold overlapping values and the footer cannot say which.docs/query-lifecycle.md — one join-plus-aggregate query traced through all six stages, with real plan output at each step and a note on what each stage decides that the one before it could not. Ends with a table of what each crate is allowed to know about, since the one-way dependency direction is the whole argument for the split.