docs: view backfill example for streams with revisions

[MicBun]

resolves: https://github.com/truflation/truflation-transformers/issues/942

Summary by CodeRabbit

• Documentation
  • Added comprehensive revision backfill example with detailed documentation and Python implementation demonstrating multi-revision per-date transaction handling, snapshot validation (latest and per-revision), block height tracking, revision-slot grouping, date conversion utilities, and complete usage instructions for reproducing the example as a standalone script.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	4h	Update time	May 6, 2026, 4:14 PM

---

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

[MicBun]

@holdex pr submit-time 4h

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 15d09ae1-7c20-4f9f-bb90-7b9269b846e8

📥 Commits

Reviewing files that changed from the base of the PR and between 225b46d and 8d0fc59.

📒 Files selected for processing (2)

• examples/revision_backfill_example/README.md
• examples/revision_backfill_example/main.py

---

📝 Walkthrough

Walkthrough

A revision backfill example is added, consisting of documentation explaining the pattern for splitting records into per-date revision slots and inserting them separately, along with a Python script that demonstrates the pattern using a TN stream with slot-based transactions and frozen_at reads for validation.

Changes

Revision Backfill Example

Layer / File(s)	Summary
Pattern Documentation examples/revision_backfill_example/README.md	Describes the revision backfill rationale, the per-date slot pattern, the Python helper function signature, and run instructions for reproducing the example.
Implementation & Utilities examples/revision_backfill_example/main.py	Implements date conversion utilities (_date_to_unix, _unix_to_iso), stream management (_safe_drop), the split_into_revision_slots grouping function, and a complete main() demo that creates a stream, inserts records grouped by revision slot, and validates both latest snapshot and per-revision reads using frozen_at.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hops through time with slots so neat,
Revisions line up, complete and sweet,
Each date gets versions, one by one,
Frozen in time—backfill is fun!
Insert, read, and validate with cheer,
The pattern's clear, the path is clear! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a backfill example for streams with revisions, which matches the addition of revision-aware backfill documentation and example code.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch revisionExamples

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}