delta-explain

delta-explain is a read‑only diagnostic tool that makes Delta Lake pruning visible. It parses a Delta table’s transaction log (or a cloud location) to illustrate how partition pruning and column statistics narrow the candidate file set for a supplied SQL‑style predicate. You can run it from the shell (`delta-explain ./my-table --where "age > 40 AND country = 'DE'"`), from Python (`from delta_explain import explain; report = explain(...)`), or embed it in CI as a gate (`--min-pruning 90 --assert-stats`). The tool never touches Parquet data files – only the log – keeping its surface small and its guarantees documented. Installation options include Homebrew, PyPI, Cargo, Docker, and pre‑built binaries. It supports local paths and cloud URIs (S3, Azure, GCS) with provider‑specific credential handling. Reports are emitted as a versioned JSON contract; a self‑contained HTML viewer can render pruning funnels, per‑file details, and diagnostics. Performance scales with the number of log entries, not data volume. On 200 k files the tool runs in ~1–2 s and uses ~300 MB of RAM. Wide schemas or many files increase memory linearly, and output size can be limited with `--limit`. The project doubles as a GitHub Action for CI gating, exposing pruning percentages and file counts as step outputs. Key features include: * Step‑by‑step pruning visualization (partition then statistics) * Verbose per‑file listings (kept/dropped reasons, sizes, stats ranges) * Threshold‑based CI gates (`--min-pruning`, `--assert-stats`) * JSON schema‑validated reports and an HTML viewer * Cross‑platform binaries (Linux, macOS, Windows) and Docker images * Full documentation, examples, and a deep‑dive article on the design. The tool is built on delta‑kernel‑rs, strictly read‑only, and released under the MIT license.