README.md

petquar

Visualize Apache Parquet file internals by reading only the footer metadata — schema, row groups, column chunk stats, encodings, compression, bloom filter / page index presence — without scanning row data.

Metadata is parsed by a small Rust extension (PyO3) that wraps the parquet crate from apache/arrow-rs, which stays current with new Parquet format features (page indexes, bloom filters, new logical types, etc).

Status

Early scaffold. Local files are supported; S3-compatible remotes are stubbed in python/petquar/reader.py for a follow-up.

Usage

petquar path/to/file.parquet

Starts a local web server and opens a browser tab visualizing the file's schema, row groups, and column chunk statistics. The server (not a static HTML dump) is intentional — it's the base for a future predicate-pushdown playground that simulates which row groups/pages a filter would prune.

Development

Requires a Rust toolchain (cargo) and maturin in addition to uv.

# one-time: install rust toolchain if you don't have it
# https://rustup.rs

uv sync                # installs Python deps (fastapi, uvicorn, ...)
uv run maturin develop # builds the Rust extension into the active venv
uv run petquar sample.parquet

Run uv run maturin develop --release for an optimized build.

Project layout

Cargo.toml               Rust crate (pyo3 extension: petquar._native)
src/lib.rs                Metadata extraction using the `parquet` crate
pyproject.toml            maturin build backend + Python project metadata
python/petquar/
  cli.py                  `petquar` entry point
  reader.py               local/remote source resolution (S3 stubbed)
  metadata.py             Python wrapper around the native extension
  server.py               FastAPI app serving metadata JSON + the UI
  static/                 frontend (schema tree, row group / column tables)