docs: document TPC-H plan-stability golden files and regeneration#1979
Merged
Merged
Conversation
Add a section to the contributor development guide explaining the tpch_plan_stability test suite: what the approved golden plans capture, that they are planned deterministically against a synthetic stats table (no data or cluster required), and how to regenerate them with dev/update-tpch-plan-stability.sh when a change intentionally alters distributed planning.
github-actions
Bot
added
the
documentation
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.
Which issue does this PR close?
Closes #.
Rationale for this change
The
tpch_plan_stabilitysuite inballista-schedulercompares the distributed physical plans for the 22 TPC-H queries against approved golden files. When a change intentionally alters distributed planning, the suite fails with a plan-drift diff and the goldens must be regenerated. This workflow was not documented anywhere in the contributor guide, so a contributor hitting the failure has no pointer todev/update-tpch-plan-stability.shor an explanation of what the goldens represent.What changes are included in this PR?
Add a "TPC-H plan-stability golden files" subsection to the contributor development guide (
docs/source/contributors-guide/development.md). It explains what the golden plans capture (stage boundaries, shuffles, exchange reuse), that they are planned deterministically against a synthetic statistics-only table so no TPC-H data or running cluster is needed, where the approved files live, and how to regenerate and review them withdev/update-tpch-plan-stability.sh.Docs-only change.
npx prettier@2.7.1reports no formatting changes.Are there any user-facing changes?
No. Documentation only; no code, API, or behavior changes.