sqlbenchdag 0.1.0__py3-none-any.whl

scripts/tools/find_kink.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Locate the scale 'kink' in a capsule: the row-count interval where an engine's
+per-decade slowdown spikes. That spike is the mathematical flare — it points
+EXPLAIN ANALYZE at the exact interval where the engine changes strategy (a sort/
+hash spilling to disk, an index scan flipping to seq/bitmap, a parallelism wall).
+
+Two corrections over a naive tmax/tmin reading:
+  * per-decade normalization — scale points are not evenly spaced (1K->100K is
+    TWO decades), so each interval's multiplier is taken as ratio**(1/decades);
+    a raw ratio would flag a false kink on the wide interval.
+  * noise awareness — each interval also reports the replication spread at its
+    endpoints, so a spike can be judged against measurement noise, not trusted
+    blindly. With few scale points a kink LOCATES where to look; EXPLAIN confirms.
+
+Reads sealed fragments only. Computes nothing that feeds the Experiment ID, so
+it never changes an ID or a seal.
+
+Usage:  python scripts/tools/find_kink.py <experiment_id> [<id> ...]
+"""
+import glob
+import json
+import math
+import os
+import statistics
+import sys
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+RESULTS = os.path.join(REPO_ROOT, "sql_benchmarks", "experiments", "results")
+
+
+def raw_points(capsule: str) -> dict:
+    """engine -> {rows: [raw durations]} from fragments with a numeric rows axis."""
+    series: dict = {}
+    for path in glob.glob(os.path.join(capsule, "fragments", "*.json")):
+        with open(path) as f:
+            data = json.load(f)
+        params = data.get("parameters", {})
+        if "rows" not in params:
+            continue
+        metrics = data.get("metrics", {})
+        raw = metrics.get("durations_raw") or (
+            [metrics["duration_seconds"]] if metrics.get("duration_seconds") is not None else []
+        )
+        if not raw:
+            continue
+        eng = data["meta"]["engine"]
+        series.setdefault(eng, {}).setdefault(int(params["rows"]), []).extend(raw)
+    return series
+
+
+def ladder(points: dict):
+    """points: {rows: [raw]} -> (median_by_n, [(n1, n2, per_decade_mult, noise)])."""
+    ns = sorted(points)
+    med = {n: statistics.median(points[n]) for n in ns}
+    rungs = []
+    for n1, n2 in zip(ns, ns[1:]):
+        decades = math.log10(n2 / n1)
+        mult = (med[n2] / med[n1]) ** (1 / decades) if decades and med[n1] else float("nan")
+        spread = max(
+            (max(points[n1]) - min(points[n1])) / med[n1] if med[n1] else 0.0,
+            (max(points[n2]) - min(points[n2])) / med[n2] if med[n2] else 0.0,
+        )
+        rungs.append((n1, n2, mult, spread))
+    return med, rungs
+
+
+def report(exp_id: str) -> None:
+    capsule = os.path.join(RESULTS, exp_id)
+    if not os.path.isdir(capsule):
+        print(f"{exp_id}: MISSING\n")
+        return
+    series = raw_points(capsule)
+    if not series:
+        print(f"{exp_id}: no row-scaled fragments (needs a numeric 'rows' axis)\n")
+        return
+    print(f"=== {exp_id} ===")
+    for eng, pts in sorted(series.items()):
+        if len(pts) < 3:
+            print(f"  {eng}: {len(pts)} scale point(s) — need >=3 (>=2 intervals) to locate a kink")
+            continue
+        med, rungs = ladder(pts)
+        mults = [m for *_, m, _ in rungs]
+        typical = statistics.median(mults)
+        kink = max(rungs, key=lambda r: r[2])
+        print(f"  {eng}:")
+        print(f"    {'interval':>20} {'per-decade':>11} {'noise(±%)':>10}")
+        for n1, n2, mult, spread in rungs:
+            mark = "  <-- KINK" if (n1, n2) == (kink[0], kink[1]) else ""
+            print(f"    {n1:>8,}->{n2:<9,} {mult:>10.2f}x {spread*100:>9.0f}%{mark}")
+        spike = kink[2] / typical if typical else float("nan")
+        verdict = (
+            f"    spike {spike:.1f}x over typical"
+            + ("  — within endpoint noise, treat as soft" if kink[2] - 1 <= kink[3] else "")
+        )
+        print(verdict)
+        print(f"    -> EXPLAIN ANALYZE {eng} at rows={kink[0]:,} vs {kink[1]:,}\n")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    for exp_id in sys.argv[1:]:
+        report(exp_id)

scripts/tools/gen_experiment_catalog.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Generate the experiment catalog from the sealed capsules.
+
+Reads every results/<ID>/experiment_config.yaml and emits a Markdown table
+(ID, name, engines, suite, sealed) into the CATALOG region of docs/experiments.md.
+The catalog is DERIVED from the capsules, so it cannot drift from what was
+actually run — regenerate it after publishing a new capsule.
+
+Usage:  python scripts/tools/gen_experiment_catalog.py [--check]
+        --check : exit non-zero if the file is out of date (for CI/pre-commit)
+"""
+import glob
+import os
+import subprocess
+import sys
+import yaml
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+RESULTS = os.path.join(REPO_ROOT, "sql_benchmarks", "experiments", "results")
+DOC = os.path.join(REPO_ROOT, "docs", "experiments.md")
+
+START = "<!-- CATALOG:START (generated by scripts/tools/gen_experiment_catalog.py — do not edit by hand) -->"
+END = "<!-- CATALOG:END -->"
+
+
+def row_for(capsule_dir: str):
+    cfg_path = os.path.join(capsule_dir, "experiment_config.yaml")
+    if not os.path.exists(cfg_path):
+        return None
+    with open(cfg_path) as f:
+        cfg = yaml.safe_load(f) or {}
+    exp_id = os.path.basename(capsule_dir)
+    meta = cfg.get("meta") or {}
+    execution = cfg.get("execution") or {}
+    name = (meta.get("name") or "—").strip().strip("'\"")
+    engines = ", ".join(execution.get("engines", [])) or "—"
+    suite = execution.get("test_suite") or "—"
+    sealed = "✓" if os.path.exists(os.path.join(capsule_dir, "integrity.seal")) else "—"
+    link = f"[`{exp_id}`](../sql_benchmarks/experiments/results/{exp_id}/)"
+    return (name, f"| {link} | {name} | {engines} | {suite} | {sealed} |")
+
+
+def tracked_capsule_ids() -> set:
+    """Capsule IDs that git actually tracks — the PUBLISHED set. results/ is
+    gitignored except a committed allowlist, so the filesystem holds local
+    scratch runs too; the catalog must list only what a cloner can see, or its
+    links 404 and it advertises experiments that aren't in the repo."""
+    out = subprocess.run(
+        ["git", "ls-files", "sql_benchmarks/experiments/results/"],
+        cwd=REPO_ROOT, capture_output=True, text=True,
+    )
+    if out.returncode != 0:
+        raise RuntimeError(f"git ls-files failed; cannot determine published set:\n{out.stderr}")
+    ids = set()
+    for line in out.stdout.splitlines():
+        parts = line.split("/")
+        if len(parts) > 4:  # sql_benchmarks/experiments/results/<ID>/...
+            ids.add(parts[3])
+    return ids
+
+
+def build_table() -> str:
+    published = tracked_capsule_ids()
+    rows = [r for d in sorted(glob.glob(os.path.join(RESULTS, "*")))
+            if os.path.isdir(d) and os.path.basename(d) in published
+            for r in [row_for(d)] if r]
+    rows.sort(key=lambda nr: nr[0].lower())  # by experiment name
+    header = ("| Capsule | Name | Engines | Suite | Sealed |\n"
+              "|---|---|---|---|---|")
+    body = "\n".join(line for _, line in rows)
+    return f"{header}\n{body}\n\n*{len(rows)} capsules. Generated from the sealed configs — regenerate with `python scripts/tools/gen_experiment_catalog.py`.*"
+
+
+def render(existing: str, table: str) -> str:
+    block = f"{START}\n{table}\n{END}"
+    if START in existing and END in existing:
+        pre = existing.split(START)[0]
+        post = existing.split(END, 1)[1]
+        return f"{pre}{block}{post}"
+    # No markers yet — append.
+    return f"{existing.rstrip()}\n\n{block}\n"
+
+
+def main():
+    check = "--check" in sys.argv[1:]
+    table = build_table()
+    existing = open(DOC).read() if os.path.exists(DOC) else "# Experiments\n"
+    updated = render(existing, table)
+    n_rows = table.count("\n| [")  # data rows (header uses "| Capsule")
+    if check:
+        if existing != updated:
+            print("docs/experiments.md catalog is OUT OF DATE — run the generator.")
+            sys.exit(1)
+        print("catalog up to date ✓")
+        return
+    with open(DOC, "w") as f:
+        f.write(updated)
+    print(f"catalog written to docs/experiments.md ({n_rows} capsules)")
+
+
+if __name__ == "__main__":
+    main()

scripts/tools/load_parquet_to_local.py

@@ -0,0 +1,98 @@
+
+import os
+import sys
+import glob
+
+# 1. SETUP PATHS INDEPENDENT OF EXECUTION CONTEXT
+# Get the directory where this script lives (Project Root)
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+
+# Ensure module imports work regardless of where script is run from
+if SCRIPT_DIR not in sys.path:
+    sys.path.append(SCRIPT_DIR)
+
+from sql_benchmarks.resources.postgres_client import PostgresClient
+# We define path manually to avoid circular dependeny or context issues
+DATA_DIR = os.path.join(SCRIPT_DIR, "data")
+
+def load_local(target_pattern="*.parquet"):
+    """
+    Loads Parquet files from data/staging into local Postgres.
+    """
+    # 2. Configuration
+    # Allow simple override via env var
+    PG_CONN = os.getenv("PG_CONN", "postgresql://postgres:password@localhost:5432/postgres")
+    STAGING_DIR = os.path.join(DATA_DIR, "staging")
+    
+    print(f"\n[INFO] 🔌 Target Database: {PG_CONN}")
+    print(f"       (Override with 'export PG_CONN=postgresql://...')")
+
+    try:
+        client = PostgresClient(PG_CONN)
+    except Exception as e:
+        print(f"[ERROR] Connection failed: {e}")
+        return
+
+    # 2. Find Files
+    search_path = os.path.join(STAGING_DIR, target_pattern)
+    files = glob.glob(search_path)
+    
+    if not files:
+        print(f"[WARN] No files found matching: {search_path}")
+        return
+
+    print(f"[INFO] Found {len(files)} files to ingest.")
+    
+    success_count = 0
+
+    # 3. Load
+    for f in files:
+        basename = os.path.basename(f)
+        table_name = basename.replace(".parquet", "").replace(".", "_")
+        
+        # Cleanup name to be SQL friendly
+        table_name = table_name.lower()
+        
+        print(f"\n---> Ingesting: {basename} -> 📦 Table: {table_name}")
+        try:
+            # We use a custom loading logic here to force lowercase columns
+            # because standard PostgresClient preserves case with quotes.
+            # 1. Read Schema
+            import polars as pl
+            df = pl.scan_parquet(f).limit(1).collect()
+            
+            # 2. Rename columns to lowercase
+            new_cols = {c: c.lower() for c in df.columns}
+            
+            # 3. Drop/Create Table with strict lowercase
+            # We can't easily use client.bulk_load directly because it infers schema internally from file.
+            # Workaround: We let client.bulk_load do its thing, BUT we patch the _create_schema method on the instance?
+            # Or better: We subclass it for this script.
+            
+            class FriendlyPostgresClient(PostgresClient):
+                def _create_schema(self, table_name, sample_df):
+                    # Rename columns in the sample DF before passing to super or custom logic
+                    # Polars rename is easy
+                    lower_map = {c: c.lower() for c in sample_df.columns}
+                    sample_df = sample_df.rename(lower_map)
+                    super()._create_schema(table_name, sample_df)
+
+            # Re-init client with friendly version
+            friendly_client = FriendlyPostgresClient(PG_CONN)
+            friendly_client.bulk_load(f, table_name)
+            
+            print("     [SUCCESS] Table created.")
+            success_count += 1
+        except Exception as e:
+            print(f"     [FAILED] {e}")
+            
+    if success_count > 0:
+        print("\n[TIP] Check your tables with:")
+        print(f"      psql '{PG_CONN}' -c '\\dt'")
+
+if __name__ == "__main__":
+    target = "*.parquet"
+    if len(sys.argv) > 1:
+        target = sys.argv[1]
+    
+    load_local(target)

scripts/tools/plot_execution_modes.py

@@ -0,0 +1,82 @@
+"""
+Generate the execution-modes figure from a result capsule.
+
+Reads raw per-replication durations from the capsule's fragments (not the
+CSV means), so the bands show the true replication spread.
+
+Usage:
+    python scripts/tools/plot_execution_modes.py <experiment_id> [output.png]
+
+Requires matplotlib (optional tooling dependency: `uv pip install matplotlib`).
+"""
+import glob
+import json
+import os
+import sys
+
+import matplotlib.pyplot as plt
+
+from _plotlib import RESULTS_DIR, style, bench_string
+
+
+def load_fragments(exp_id):
+    pattern = os.path.join(RESULTS_DIR, exp_id, "fragments", "*.json")
+    series = {}  # engine -> [(rows, raw_durations_ms)]
+    for path in glob.glob(pattern):
+        with open(path) as f:
+            data = json.load(f)
+        engine = data["meta"]["engine"]
+        rows = int(data["parameters"]["rows"])
+        raw = data["metrics"].get("durations_raw") or []
+        if not raw:
+            continue  # DNF
+        series.setdefault(engine, []).append((rows, [d * 1000 for d in raw]))
+    for engine in series:
+        series[engine].sort()
+    return series
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    exp_id = sys.argv[1]
+    out = sys.argv[2] if len(sys.argv) > 2 else os.path.join("docs", "figures", f"execution_modes_{exp_id}.png")
+
+    series = load_fragments(exp_id)
+    if not series:
+        sys.exit(f"No fragments with raw durations found for '{exp_id}'")
+
+    meta_path = os.path.join(RESULTS_DIR, exp_id, f"metadata_{exp_id}.json")
+    env = {}
+    if os.path.exists(meta_path):
+        with open(meta_path) as f:
+            env = json.load(f).get("environment", {})
+
+    fig, ax = plt.subplots(figsize=(8, 5))
+    for engine, points in series.items():
+        label, color, marker = style(engine)
+        xs = [rows for rows, _ in points]
+        med = [sorted(raw)[len(raw) // 2] for _, raw in points]
+        lo = [min(raw) for _, raw in points]
+        hi = [max(raw) for _, raw in points]
+        ax.plot(xs, med, marker=marker, color=color, label=label, linewidth=2)
+        ax.fill_between(xs, lo, hi, color=color, alpha=0.18)
+
+    ax.set_xscale("log")
+    ax.set_yscale("log")
+    ax.set_xlabel("Table rows (log scale)")
+    ax.set_ylabel("Query duration, ms (log scale, median of replications)")
+    bench = bench_string(env, engines=series.keys())
+    ax.set_title(f"Query cost by engine — experiment {exp_id}\n"
+                 f"cold cache, bands = replication min–max · {bench}", fontsize=10)
+    ax.legend(frameon=False)
+    ax.grid(True, which="both", alpha=0.25)
+    fig.tight_layout()
+
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    fig.savefig(out, dpi=160)
+    print(f"Figure written: {out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/tools/plot_scaling.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Log-log scaling figure (median duration vs row count) for a row-scaled capsule,
+built ONLY from the capsule's sealed fragments — regenerable, can't drift.
+Error bars show the replication spread where more than one rep was retained.
+
+Usage:  python scripts/tools/plot_scaling.py <experiment_id> [<id> ...]
+Output: scratch/figures/scaling_<id>.png  (gitignored; for the article)
+"""
+import glob
+import json
+import math
+import os
+import statistics
+import sys
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from _plotlib import REPO_ROOT, RESULTS_DIR, style
+
+OUT = os.path.join(REPO_ROOT, "scratch", "figures")
+
+
+def series(capsule: str) -> dict:
+    s: dict = {}
+    for p in glob.glob(os.path.join(capsule, "fragments", "*.json")):
+        with open(p) as f:
+            d = json.load(f)
+        par, m = d.get("parameters", {}), d.get("metrics", {})
+        if "rows" not in par:
+            continue
+        raw = m.get("durations_raw") or (
+            [m["duration_seconds"]] if m.get("duration_seconds") is not None else []
+        )
+        if raw:
+            s.setdefault(d["meta"]["engine"], {}).setdefault(int(par["rows"]), []).extend(raw)
+    return s
+
+
+def alpha(points: dict) -> float:
+    """log-log least-squares slope (power-law exponent)."""
+    xs = [math.log10(n) for n in points]
+    ys = [math.log10(statistics.median(points[n])) for n in points]
+    k = len(xs)
+    mx, my = sum(xs) / k, sum(ys) / k
+    sxx = sum((x - mx) ** 2 for x in xs)
+    return sum((xs[i] - mx) * (ys[i] - my) for i in range(k)) / sxx if sxx else 0.0
+
+
+def plot(exp_id: str) -> None:
+    capsule = os.path.join(RESULTS_DIR, exp_id)
+    s = series(capsule)
+    if not s:
+        print(f"{exp_id}: no row-scaled fragments — skipped")
+        return
+    os.makedirs(OUT, exist_ok=True)
+    plt.figure(figsize=(7, 5))
+    for eng in sorted(s):
+        pts = s[eng]
+        ns = sorted(pts)
+        med = [statistics.median(pts[n]) * 1000 for n in ns]
+        a = alpha(pts)
+        label, color, marker = style(eng)
+        lo = [(statistics.median(pts[n]) - min(pts[n])) * 1000 for n in ns]
+        hi = [(max(pts[n]) - statistics.median(pts[n])) * 1000 for n in ns]
+        if any(l > 0 or h > 0 for l, h in zip(lo, hi)):
+            plt.errorbar(ns, med, yerr=[lo, hi], marker=marker, color=color,
+                         capsize=3, label=f"{label}  (α≈{a:.2f})")
+        else:
+            plt.plot(ns, med, marker=marker, color=color, label=f"{label}  (α≈{a:.2f})")
+    plt.xscale("log")
+    plt.yscale("log")
+    plt.xlabel("Rows (log scale)")
+    plt.ylabel("Median duration, ms (log scale)")
+    plt.title(f"Scaling: duration vs rows — {exp_id}")
+    plt.legend()
+    plt.grid(True, which="both", ls=":", alpha=0.4)
+    out = os.path.join(OUT, f"scaling_{exp_id}.png")
+    plt.tight_layout()
+    plt.savefig(out, dpi=150)
+    plt.close()
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    for exp_id in sys.argv[1:]:
+        plot(exp_id)

scripts/tools/plot_selectivity.py

@@ -0,0 +1,139 @@
+"""
+Generate the selectivity-sweep figure from the selectivity capsules.
+
+Plots query time vs predicate selectivity at a fixed scale (default 10M rows),
+overlaying five lanes: in-process DuckDB, Quack attach, Quack pushdown, and
+PostgreSQL with and without a B-tree index on the filtered column. The two
+Postgres lanes come from two capsules (indexed vs no-index); the three
+columnar/Quack lanes are read from the indexed capsule.
+
+Usage:
+    python scripts/tools/plot_selectivity.py [indexed_id] [noindex_id] [partition] [out.png]
+    # defaults: 461beee8 28f7aa1c large docs/figures/selectivity_461beee8.png
+
+Requires matplotlib (optional tooling dependency: `uv pip install matplotlib`).
+"""
+import csv
+import json
+import os
+import sys
+
+import matplotlib.pyplot as plt
+
+RESULTS_DIR = os.path.join("sql_benchmarks", "experiments", "results")
+
+# selectivity token -> (label, x-position)
+SEL = [("0_1", "0.1%"), ("1", "1%"), ("5", "5%"),
+       ("10", "10%"), ("20", "20%"), ("filler", "scan")]
+
+
+def _token(asset):
+    for tok, _ in SEL:
+        suffix = "q_filler" if tok == "filler" else f"q_{tok}_percent"
+        if asset.endswith(suffix):
+            return tok
+    return None
+
+
+def load(cid, partition):
+    """engine -> {sel_token: (median_ms, min_ms, max_ms)}"""
+    out = {}
+    path = os.path.join(RESULTS_DIR, cid, f"{cid}.csv")
+    with open(path) as f:
+        for r in csv.DictReader(f):
+            if r["Partition"] != partition:
+                continue
+            tok = _token(r["Asset"])
+            if tok is None:
+                continue
+            out.setdefault(r["Engine"], {})[tok] = (
+                float(r["Duration"]) * 1000,
+                float(r["Duration_Min"]) * 1000,
+                float(r["Duration_Max"]) * 1000,
+            )
+    return out
+
+
+def series(data, engine):
+    xs, ys, lo, hi = [], [], [], []
+    for i, (tok, _) in enumerate(SEL):
+        if engine in data and tok in data[engine]:
+            m, a, b = data[engine][tok]
+            xs.append(i); ys.append(m); lo.append(m - a); hi.append(b - m)
+    return xs, ys, lo, hi
+
+
+def main():
+    indexed = sys.argv[1] if len(sys.argv) > 1 else "461beee8"
+    noindex = sys.argv[2] if len(sys.argv) > 2 else "28f7aa1c"
+    partition = sys.argv[3] if len(sys.argv) > 3 else "large"
+    out = sys.argv[4] if len(sys.argv) > 4 else os.path.join(
+        "docs", "figures", f"selectivity_{indexed}.png")
+
+    idx = load(indexed, partition)
+    noi = load(noindex, partition)
+
+    meta_path = os.path.join(RESULTS_DIR, indexed, f"metadata_{indexed}.json")
+    env = {}
+    if os.path.exists(meta_path):
+        with open(meta_path) as f:
+            env = json.load(f).get("environment", {})
+
+    # lane -> (source data, engine key, label, color, marker, linestyle)
+    lanes = [
+        (idx, "duckdb",         "DuckDB in-process",        "#2f6f4f", "o", "-"),
+        (idx, "quack_pushdown", "Quack pushdown",           "#3b6ea5", "^", "-"),
+        (idx, "quack",          "Quack attach",             "#b3402a", "s", "-"),
+        (idx, "postgres",       "PostgreSQL + index",       "#7a5ea8", "D", "-"),
+        (noi, "postgres",       "PostgreSQL no index",      "#999999", "v", "--"),
+    ]
+
+    fig, ax = plt.subplots(figsize=(9, 5.5))
+    for data, eng, label, color, marker, ls in lanes:
+        xs, ys, lo, hi = series(data, eng)
+        if not xs:
+            continue
+        ax.errorbar(xs, ys, yerr=[lo, hi], label=label, color=color,
+                    marker=marker, linestyle=ls, capsize=3, linewidth=1.8,
+                    markersize=6)
+
+    ax.set_yscale("log")
+    ax.set_xticks(range(len(SEL)))
+    ax.set_xticklabels([lbl for _, lbl in SEL])
+    ax.set_xlabel("predicate selectivity (fraction of rows matched)")
+    ax.set_ylabel("query time (ms, log scale) — cold cache, 5 reps")
+    rows = "10M" if partition == "large" else "1M"
+    ax.set_title(f"Selectivity sweep @ {rows} rows: where does the index help — and hurt?")
+
+    # Annotate the Postgres-index plan transitions (EXPLAIN-verified).
+    if "postgres" in idx:
+        ax.annotate("Index-Only Scan", xy=(0, idx["postgres"]["0_1"][0]),
+                    xytext=(0.1, idx["postgres"]["0_1"][0] * 0.45),
+                    fontsize=8, color="#7a5ea8")
+        if "5" in idx["postgres"]:
+            ax.annotate("Bitmap Heap Scan\n(index becomes a liability)",
+                        xy=(2, idx["postgres"]["5"][0]),
+                        xytext=(2.35, idx["postgres"]["5"][0] * 0.62),
+                        fontsize=8, color="#7a5ea8",
+                        arrowprops=dict(arrowstyle="->", color="#7a5ea8", lw=0.8))
+
+    ax.grid(True, which="both", axis="y", alpha=0.25)
+    ax.legend(frameon=False, fontsize=9, loc="center right")
+
+    sub = f"capsules {indexed} (indexed) + {noindex} (no index)"
+    if env:
+        cores = env.get("cpu_count_logical")
+        bits = [env.get("os", ""), env.get("machine", "")]
+        if cores:
+            bits.append(f"{cores} cores")
+        sub += "  ·  " + ", ".join(b for b in bits if b)
+    fig.text(0.5, 0.005, sub, ha="center", fontsize=7.5, color="#666666")
+
+    fig.tight_layout(rect=(0, 0.02, 1, 1))
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    fig.savefig(out, dpi=150)
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    main()