Skip to content

docs: declare history tables with a required_filter on the validity column - #166

Merged
flyersworder merged 2 commits into
mainfrom
docs/history-table-relationships
Nov 9, 2026
Merged

flyersworder merged 2 commits into
mainfrom
docs/history-table-relationships

Conversation

@flyersworder

@flyersworder flyersworder commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • A history table declared many_to_one double-counts when joined on the key alone: every version matches, nothing errors, and the fan-out check stays silent.
  • New README recipe: the business picks a version rule and declares it as the join's required_filter, which the agent sees as a condition it must apply.
    • As of the fact's date (half-open interval): order_date >= valid_from AND (valid_to IS NULL OR order_date < valid_to)
    • Current version: valid_to IS NULL
  • With either rule the key-only join warns, and the rule passes in WHERE or ON. The as-of rule also flags a current-only join and a missing lower bound.
  • The README states three limitations of the name-based check: another table's column of the same name satisfies it, a multi-version filter (valid_to IS NOT NULL) satisfies the current rule, and a correct as-of LEFT JOIN still warns on the preserved-side order_date.
  • TestHistoryTable (12 tests) pins every case and every limitation the recipe states.

Docs and tests only; no library change, no release. Follow-up candidate, not in this PR: count a preserved-side column in an outer join's ON when its predicate also references the null-extended side, which would clear the as-of LEFT JOIN false warning.

Test plan

  • uv run pytest (3,257 passed)
  • prek run --all-files clean
  • Medium code review run; all 8 findings addressed

🤖 Generated with Claude Code

flyersworder and others added 2 commits November 9, 2026 21:44
…olumn

A history (slowly changing) table declared many_to_one silently multiplies
facts when joined on the key alone: every version matches, nothing errors,
and the fan-out check stays quiet because the declared cardinality is
many_to_one. The existing required_filter already covers it — a filter on
valid_to flags the key-only join and accepts both the current-version and
the as-of join — but nothing said so.

Adds a "History tables" recipe to the README and TestHistoryTable to pin
the behaviour it describes, including the silent case that motivates it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review of #166: the agent sees required_filter as a condition it must
apply, so `valid_to IS NULL` beside an as-of description contradicted
itself. The recipe now declares one rule — as of the fact's date with a
half-open interval, or the current version — as the required_filter. The
as-of rule also flags a current-only join and a missing lower bound.

Drops the "same total" claim, which fails for inner joins, and states the
limitations of a name-based check: another table's column satisfies it,
a multi-version filter satisfies the current rule, and a correct as-of
LEFT JOIN warns on the preserved-side order_date. Each is pinned by a test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@flyersworder
flyersworder merged commit 91384b5 into main Nov 9, 2026
9 checks passed
@flyersworder
flyersworder deleted the docs/history-table-relationships branch November 9, 2026 20:52
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