dataxplan 0.1.0__py3-none-any.whl

dataxplan/__init__.py

@@ -0,0 +1,45 @@
+"""dataxplan - read PostgreSQL EXPLAIN plans, locally and deterministically.
+
+Give it the output of ``EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ...`` and it
+parses the plan, computes the metrics people misread (self time, estimation
+error, disk spills), and flags documented problems. No database connection is
+required and nothing leaves your machine.
+
+    import dataxplan
+
+    report = dataxplan.analyze(explain_json)
+    print(report.summary())
+
+    # guard a plan in a test (fail CI if it regresses)
+    assert not report.has_seq_scan_on("orders")
+    assert report.max_estimation_error < 100
+    assert not report.spilled_to_disk
+
+    # compare two plans (before/after an index)
+    print(dataxplan.compare(before_json, after_json).summary())
+
+The findings are documented heuristics, not guarantees, and the analysis is of
+the plan you provide; it does not run your queries or read your schema unless you
+choose to supply catalog context.
+"""
+
+from ._result import Finding
+from ._version import __version__
+from .compare import Comparison, compare
+from .context import Context, TableInfo
+from .metrics import NodeMetrics
+from .parse import Plan, PlanNode, parse
+from .render import plan_tree_chart, text_tree
+from .report import Report, analyze
+from .run import run_explain
+
+__all__ = [
+    # core flow
+    "parse", "analyze", "compare",
+    # types
+    "Plan", "PlanNode", "Report", "NodeMetrics", "Finding", "Comparison",
+    "Context", "TableInfo",
+    # render and helpers
+    "text_tree", "plan_tree_chart", "run_explain",
+    "__version__",
+]

dataxplan/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

dataxplan/_result.py

@@ -0,0 +1,83 @@
+"""Shared plumbing: provenance (version, input hash, timestamp), the ``Finding``
+type, and small formatting helpers. Every public result carries a meta block so
+an analysis can be reproduced and audited later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from ._version import __version__
+
+SCHEMA = 1
+
+# Finding severities, most to least serious.
+HIGH = "high"
+MEDIUM = "medium"
+LOW = "low"
+INFO = "info"
+_ORDER = {HIGH: 0, MEDIUM: 1, LOW: 2, INFO: 3}
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def data_hash(obj: object) -> str:
+    payload = json.dumps(obj, sort_keys=True, default=str).encode("utf-8")
+    return "sha256:" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+def make_meta(inputs: dict) -> dict:
+    """The provenance block stamped onto every result."""
+    return {
+        "library": "dataxplan",
+        "version": __version__,
+        "computed_at": utcnow(),
+        "input_hash": data_hash(inputs),
+    }
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One observation about a plan: a documented heuristic, not a guarantee."""
+
+    id: str
+    severity: str           # high | medium | low | info
+    title: str
+    detail: str
+    node: str | None = None         # e.g. "Seq Scan on orders"
+    path: tuple[int, ...] | None = None
+    suggestion: str | None = None
+
+    @property
+    def rank(self) -> int:
+        return _ORDER.get(self.severity, 9)
+
+    def __str__(self) -> str:
+        head = f"[{self.severity.upper()}] {self.title}"
+        if self.node:
+            head += f"  ({self.node})"
+        lines = [head, f"    {self.detail}"]
+        if self.suggestion:
+            lines.append(f"    -> {self.suggestion}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id, "severity": self.severity, "title": self.title,
+            "detail": self.detail, "node": self.node,
+            "path": list(self.path) if self.path else None,
+            "suggestion": self.suggestion,
+        }
+
+
+def ms(value: float | None) -> str:
+    return "-" if value is None else f"{value:,.2f} ms"
+
+
+def num(value: float | None, places: int = 0) -> str:
+    return "-" if value is None else f"{value:,.{places}f}"

dataxplan/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dataxplan/cli.py

@@ -0,0 +1,66 @@
+"""Command-line interface: analyse a plan from a file or stdin.
+
+    dataxplan plan.json
+    dataxplan plan.json --tree
+    dataxplan plan.json --json
+    dataxplan before.json --compare after.json
+    psql -XqAt -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ..." | dataxplan
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import analyze, compare, text_tree
+from ._version import __version__
+
+
+def _read(source: str) -> str:
+    if source in (None, "-"):
+        return sys.stdin.read()
+    with open(source, encoding="utf-8") as handle:
+        return handle.read()
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="dataxplan",
+        description="Analyse a PostgreSQL EXPLAIN (FORMAT JSON) plan, locally.")
+    parser.add_argument("plan", nargs="?", default="-",
+                        help="plan file, or - for stdin (the default)")
+    parser.add_argument("--tree", action="store_true",
+                        help="also print the annotated plan tree")
+    parser.add_argument("--json", action="store_true",
+                        help="print the full report (or comparison) as JSON")
+    parser.add_argument("--compare", metavar="OTHER",
+                        help="compare the plan against another plan file")
+    parser.add_argument("--version", action="version",
+                        version=f"dataxplan {__version__}")
+    args = parser.parse_args(argv)
+
+    try:
+        plan = json.loads(_read(args.plan))
+        if args.compare:
+            result = compare(plan, json.loads(_read(args.compare)))
+            print(json.dumps(result.to_dict(), indent=2, default=str)
+                  if args.json else result.summary())
+            return 0
+        report = analyze(plan)
+    except (ValueError, TypeError, OSError, json.JSONDecodeError) as exc:
+        print(f"dataxplan: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, default=str))
+    else:
+        print(report.summary())
+        if args.tree:
+            print("\nplan tree:")
+            print(text_tree(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dataxplan/compare.py

@@ -0,0 +1,115 @@
+"""Compare two plans for regression: did a change make a query slower, change
+its shape, or worsen its estimates? Useful before/after an index, a query
+rewrite or a schema change, and as a guard in CI.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._result import make_meta, ms
+from .report import Report, analyze
+
+
+def _as_report(x) -> Report:
+    return x if isinstance(x, Report) else analyze(x)
+
+
+def _self_by_label(report: Report) -> dict:
+    out: dict = {}
+    for m in report.metrics:
+        out[m.label] = out.get(m.label, 0.0) + (m.self_time or 0.0)
+    return out
+
+
+@dataclass(frozen=True)
+class Comparison:
+    before_time_ms: float | None
+    after_time_ms: float | None
+    delta_ms: float | None
+    delta_pct: float | None
+    node_deltas: tuple[dict, ...]
+    appeared: tuple[str, ...]
+    disappeared: tuple[str, ...]
+    new_findings: tuple[str, ...]
+    resolved_findings: tuple[str, ...]
+    before_max_error: float
+    after_max_error: float
+    verdict: str            # improved | regressed | similar
+    meta: dict
+
+    def summary(self) -> str:
+        lines = [f"dataxplan compare - {self.verdict.upper()}"]
+        if self.before_time_ms is not None and self.after_time_ms is not None:
+            d = "" if self.delta_pct is None else f" ({self.delta_pct:+.0%})"
+            lines.append(f"  execution time   {ms(self.before_time_ms)} -> "
+                         f"{ms(self.after_time_ms)}{d}")
+        if self.appeared:
+            lines.append(f"  new nodes        {', '.join(self.appeared)}")
+        if self.disappeared:
+            lines.append(f"  gone nodes       {', '.join(self.disappeared)}")
+        if self.new_findings:
+            lines.append(f"  new findings     {', '.join(self.new_findings)}")
+        if self.resolved_findings:
+            lines.append(f"  resolved         {', '.join(self.resolved_findings)}")
+        big = [d for d in self.node_deltas if abs(d["delta_ms"] or 0) > 0][:5]
+        if big:
+            lines.append("  largest self-time changes:")
+            for d in big:
+                lines.append(f"    {d['label']:<32} {d['delta_ms']:+,.2f} ms")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "schema": 1, "verdict": self.verdict,
+            "before_time_ms": self.before_time_ms, "after_time_ms": self.after_time_ms,
+            "delta_ms": self.delta_ms, "delta_pct": self.delta_pct,
+            "node_deltas": list(self.node_deltas), "appeared": list(self.appeared),
+            "disappeared": list(self.disappeared),
+            "new_findings": list(self.new_findings),
+            "resolved_findings": list(self.resolved_findings),
+            "before_max_error": self.before_max_error,
+            "after_max_error": self.after_max_error, "meta": self.meta,
+        }
+
+
+def compare(before, after) -> Comparison:
+    """Compare two plans (``Report`` objects or raw EXPLAIN output)."""
+    a, b = _as_report(before), _as_report(after)
+    bt, at = a.execution_time_ms, b.execution_time_ms
+
+    delta = dpct = None
+    if bt is not None and at is not None:
+        delta = at - bt
+        dpct = (delta / bt) if bt else None
+        threshold = 0.05 * bt
+        verdict = ("regressed" if delta > threshold
+                   else "improved" if delta < -threshold else "similar")
+    else:
+        bc, ac = a.plan.root.total_cost, b.plan.root.total_cost
+        verdict = ("regressed" if ac > 1.05 * bc
+                   else "improved" if ac < 0.95 * bc else "similar")
+
+    sb, sa = _self_by_label(a), _self_by_label(b)
+    labels = sorted(set(sb) | set(sa))
+    node_deltas = tuple(sorted(
+        ({"label": lb, "before_ms": sb.get(lb), "after_ms": sa.get(lb),
+          "delta_ms": (sa.get(lb, 0.0) - sb.get(lb, 0.0))} for lb in labels),
+        key=lambda d: abs(d["delta_ms"] or 0), reverse=True))
+
+    before_labels = {m.label for m in a.metrics}
+    after_labels = {m.label for m in b.metrics}
+    bf = {f.id for f in a.findings if f.id != "clean"}
+    af = {f.id for f in b.findings if f.id != "clean"}
+
+    return Comparison(
+        before_time_ms=bt, after_time_ms=at, delta_ms=delta, delta_pct=dpct,
+        node_deltas=node_deltas,
+        appeared=tuple(sorted(after_labels - before_labels)),
+        disappeared=tuple(sorted(before_labels - after_labels)),
+        new_findings=tuple(sorted(af - bf)),
+        resolved_findings=tuple(sorted(bf - af)),
+        before_max_error=a.max_estimation_error,
+        after_max_error=b.max_estimation_error,
+        verdict=verdict,
+        meta=make_meta({"before_time": bt, "after_time": at}))

dataxplan/context.py

@@ -0,0 +1,62 @@
+"""Optional catalog context.
+
+The core analysis works from the plan alone. When the caller can supply a little
+metadata from the database catalog (table sizes, the columns that are indexed,
+the server's ``work_mem``), the findings get sharper: a sequential scan on a
+known-large table with no index on the filtered column is a stronger signal than
+a sequential scan in isolation. Context is data the caller provides; the library
+never connects to a database to fetch it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class TableInfo:
+    """What we may know about one table."""
+
+    name: str
+    row_count: float | None = None
+    indexed_columns: tuple[str, ...] = ()      # columns that appear in some index
+    analyzed: bool = True                       # False if statistics look stale
+
+    def has_index_on(self, column: str) -> bool:
+        return column in self.indexed_columns
+
+
+@dataclass(frozen=True)
+class Context:
+    """Catalog metadata the caller knows, keyed by table name."""
+
+    tables: dict = field(default_factory=dict)   # name -> TableInfo
+    work_mem_mb: float | None = None
+
+    def table(self, name: str | None) -> TableInfo | None:
+        if name is None:
+            return None
+        return self.tables.get(name)
+
+
+def as_context(value) -> Context | None:
+    """Accept a :class:`Context`, a mapping, or None."""
+    if value is None or isinstance(value, Context):
+        return value
+    if isinstance(value, Mapping):
+        tables = {}
+        raw_tables = value.get("tables", {})
+        for name, info in raw_tables.items():
+            if isinstance(info, TableInfo):
+                tables[name] = info
+            elif isinstance(info, Mapping):
+                tables[name] = TableInfo(
+                    name=name,
+                    row_count=info.get("row_count"),
+                    indexed_columns=tuple(info.get("indexed_columns", ())),
+                    analyzed=info.get("analyzed", True))
+            else:
+                raise TypeError(f"table info for '{name}' must be a mapping")
+        return Context(tables=tables, work_mem_mb=value.get("work_mem_mb"))
+    raise TypeError("context must be a Context, a mapping, or None")

dataxplan/findings.py

@@ -0,0 +1,164 @@
+"""Heuristic rules that turn metrics into findings.
+
+Each rule encodes a documented PostgreSQL behaviour (see the references in the
+README). A finding is an observation with an explanation and, where reasonable,
+a suggestion; it is never a promise that a change will help. When catalog
+context is supplied the messages are sharpened, but every rule works from the
+plan alone.
+"""
+
+from __future__ import annotations
+
+from ._result import HIGH, INFO, LOW, MEDIUM, Finding
+from .context import Context
+from .metrics import NodeMetrics
+from .parse import Plan, PlanNode
+
+DEFAULT_THRESHOLDS = {
+    "estimation_error_high": 100.0,   # x off -> high severity
+    "estimation_error_med": 10.0,     # x off -> medium (if the node matters)
+    "seq_scan_pct": 0.30,             # share of execution time
+    "filter_discard_ratio": 10.0,     # rows removed vs rows kept
+    "nested_loop_loops": 1000.0,      # inner executions
+    "heap_fetch_ratio": 0.10,         # heap fetches vs rows
+    "jit_pct": 0.25,                  # JIT time vs execution time
+}
+
+
+def _pct(value: float | None) -> str:
+    return "-" if value is None else f"{100 * value:.0f}%"
+
+
+def run_findings(plan: Plan, metrics: list[NodeMetrics],
+                 context: Context | None, thresholds: dict) -> list[Finding]:
+    t = {**DEFAULT_THRESHOLDS, **(thresholds or {})}
+    by_path: dict[tuple, PlanNode] = {n.path: n for n in plan.root.walk()}
+    found: list[Finding] = []
+
+    for m in metrics:
+        node = by_path[m.path]
+        ctx_table = context.table(m.relation) if context else None
+
+        # 1. Row estimate far from reality (the usual root cause).
+        if m.estimation_error is not None:
+            sev = None
+            if m.estimation_error >= t["estimation_error_high"]:
+                sev = HIGH
+            elif (m.estimation_error >= t["estimation_error_med"]
+                  and (m.pct_self or 0) >= 0.10):
+                sev = MEDIUM
+            if sev:
+                direction = "under" if (m.estimation_factor or 1) > 1 else "over"
+                detail = (f"estimated {m.plan_rows:,.0f} rows, actual "
+                          f"{m.actual_rows:,.0f} ({m.estimation_error:.0f}x "
+                          f"{direction}-estimate)")
+                sug = ("run ANALYZE on the table; if the columns are correlated "
+                       "consider extended statistics (CREATE STATISTICS)")
+                if ctx_table is not None and not ctx_table.analyzed:
+                    sug = "statistics look stale; run ANALYZE on " + m.relation
+                found.append(Finding("estimate_off", sev, "Row estimate is far off",
+                                     detail, m.label, m.path, sug))
+
+        # 2. Sequential scan taking a large share of the time.
+        if (m.node_type == "Seq Scan" and m.relation
+                and (m.pct_self or 0) >= t["seq_scan_pct"]):
+            size = (f" ({ctx_table.row_count:,.0f} rows)"
+                    if ctx_table and ctx_table.row_count else "")
+            detail = (f"sequential scan{size} is {_pct(m.pct_self)} of execution "
+                      f"time, reading {m.actual_rows:,.0f} rows"
+                      if m.actual_rows is not None else
+                      f"sequential scan{size} is {_pct(m.pct_self)} of execution time")
+            sug = f"consider an index supporting the filter or join on {m.relation}"
+            if ctx_table is not None and ctx_table.indexed_columns:
+                sug += (f" (existing indexes cover: "
+                        f"{', '.join(ctx_table.indexed_columns)})")
+            found.append(Finding("seq_scan_hot", HIGH, "Hot sequential scan",
+                                 detail, m.label, m.path, sug))
+
+        # 3. A sort or hash spilled to disk.
+        if m.spilled:
+            if node.sort_method and "external" in node.sort_method.lower():
+                what = f"sort spilled to disk ({node.sort_method})"
+            elif (node.hash_batches or 0) > 1:
+                what = f"hash spilled to disk ({node.hash_batches:.0f} batches)"
+            else:
+                what = f"wrote {node.temp_written:,.0f} temp blocks to disk"
+            mem = (f"; work_mem is {context.work_mem_mb:.0f} MB"
+                   if context and context.work_mem_mb else "")
+            found.append(Finding(
+                "disk_spill", MEDIUM, "Operation spilled to disk",
+                what + mem, m.label, m.path,
+                "raise work_mem for this query, or reduce the rows being "
+                "sorted or hashed"))
+
+        # 4. Reading many rows and discarding most (non-sargable / missing index).
+        removed = m.rows_removed_by_filter
+        if (removed is not None and m.actual_rows is not None
+                and removed >= t["filter_discard_ratio"] * (m.actual_rows + 1)
+                and "Scan" in m.node_type):
+            detail = (f"removed {removed:,.0f} rows by filter but kept only "
+                      f"{m.actual_rows:,.0f}")
+            found.append(Finding(
+                "filter_discard", MEDIUM, "Filter discards most rows read", detail,
+                m.label, m.path,
+                "the predicate is not selective via the current access path; an "
+                "index on the filtered column may help"))
+
+        # 5. Nested loop driving its inner side many times.
+        if m.node_type == "Nested Loop" and node.children:
+            inner_loops = max((c.actual_loops for c in node.children), default=0)
+            if inner_loops >= t["nested_loop_loops"]:
+                found.append(Finding(
+                    "nested_loop_blowup", MEDIUM, "Nested loop with many iterations",
+                    f"the inner side executed {inner_loops:,.0f} times", m.label,
+                    m.path,
+                    "usually an under-estimate upstream; check the row estimates, a "
+                    "hash or merge join may be cheaper"))
+
+        # 6. Index-only scan still hitting the heap (visibility map not set).
+        if (m.node_type == "Index Only Scan" and m.heap_fetches
+                and m.actual_rows is not None
+                and m.heap_fetches >= t["heap_fetch_ratio"] * (m.actual_rows + 1)):
+            found.append(Finding(
+                "index_only_heap_fetches", LOW,
+                "Index-only scan with many heap fetches",
+                f"{m.heap_fetches:,.0f} heap fetches for {m.actual_rows:,.0f} rows",
+                m.label, m.path,
+                "VACUUM the table so the visibility map lets the scan skip the heap"))
+
+        # 7. Lossy bitmap heap scan (work_mem too small for the bitmap).
+        recheck = node.raw.get("Rows Removed by Index Recheck")
+        if m.node_type == "Bitmap Heap Scan" and recheck:
+            found.append(Finding(
+                "lossy_bitmap", LOW, "Bitmap heap scan went lossy",
+                f"{float(recheck):,.0f} rows rechecked after a lossy bitmap",
+                m.label, m.path,
+                "raise work_mem so the bitmap stays exact"))
+
+    # 8. JIT overhead on a short query.
+    jit = plan.jit
+    if jit and plan.execution_time:
+        total = (jit.get("Timing", {}) or {}).get("Total")
+        if total and plan.execution_time and total >= t["jit_pct"] * plan.execution_time:
+            found.append(Finding(
+                "jit_overhead", LOW, "JIT compilation is a large share of the time",
+                f"JIT took {total:,.1f} ms of {plan.execution_time:,.1f} ms total",
+                None, None,
+                "for short, frequent queries consider raising jit_above_cost or "
+                "turning JIT off"))
+
+    if not found:
+        found.append(Finding("clean", INFO, "No issues flagged",
+                             "no heuristic flagged this plan", None, None, None))
+
+    found.sort(key=lambda f: (f.rank, -(_self_pct(metrics, f.path))))
+    return found
+
+
+def _self_pct(metrics: list[NodeMetrics], path) -> float:
+    if path is None:
+        return 0.0
+    for m in metrics:
+        if m.path == path:
+            return m.pct_self or 0.0
+    return 0.0

dataxplan/metrics.py

@@ -0,0 +1,104 @@
+"""Derived metrics for a parsed plan.
+
+The two numbers people most often get wrong when reading a plan are computed
+here: the *self* (exclusive) time of a node, and the *estimation error*.
+
+* Postgres reports ``Actual Total Time`` per loop and inclusive of children, so a
+  node's total time is ``Actual Total Time x Actual Loops`` and its self time is
+  that minus the total time of its children. Self time shows where the work
+  actually happens.
+* ``Plan Rows`` (estimated) against ``Actual Rows`` gives the estimation error,
+  the usual root cause of a bad plan.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .parse import Plan
+
+
+@dataclass(frozen=True)
+class NodeMetrics:
+    path: tuple[int, ...]
+    label: str
+    node_type: str
+    relation: str | None
+    loops: float
+    inclusive_time: float | None
+    self_time: float | None
+    pct_self: float | None
+    plan_rows: float
+    actual_rows: float | None
+    estimation_factor: float | None   # actual / estimated, per loop (>1 under-estimate)
+    estimation_error: float | None    # how many times off, max(factor, 1/factor)
+    spilled: bool
+    shared_read: float
+    rows_removed_by_filter: float | None
+    heap_fetches: float | None
+
+    def to_dict(self) -> dict:
+        return {
+            "path": list(self.path), "label": self.label,
+            "node_type": self.node_type, "relation": self.relation,
+            "loops": self.loops, "inclusive_time_ms": self.inclusive_time,
+            "self_time_ms": self.self_time, "pct_self": self.pct_self,
+            "plan_rows": self.plan_rows, "actual_rows": self.actual_rows,
+            "estimation_factor": self.estimation_factor,
+            "estimation_error": self.estimation_error, "spilled": self.spilled,
+            "shared_read_blocks": self.shared_read,
+            "rows_removed_by_filter": self.rows_removed_by_filter,
+            "heap_fetches": self.heap_fetches,
+        }
+
+
+def compute_metrics(plan: Plan) -> list[NodeMetrics]:
+    denom = plan.execution_time or plan.root.inclusive_time
+    out: list[NodeMetrics] = []
+    for node in plan.root.walk():
+        incl = node.inclusive_time
+        if incl is not None:
+            kids = sum(c.inclusive_time or 0.0 for c in node.children)
+            self_t = max(0.0, incl - kids)
+        else:
+            self_t = None
+        pct = (self_t / denom) if (self_t is not None and denom) else None
+
+        actual = node.actual_rows
+        if actual is not None:
+            est = max(node.plan_rows, 1.0)
+            act = max(actual, 1.0)
+            factor = act / est
+            error = max(factor, 1.0 / factor)
+        else:
+            factor = error = None
+
+        out.append(NodeMetrics(
+            path=node.path, label=node.label, node_type=node.node_type,
+            relation=node.relation, loops=node.actual_loops, inclusive_time=incl,
+            self_time=self_t, pct_self=pct, plan_rows=node.plan_rows,
+            actual_rows=actual, estimation_factor=factor, estimation_error=error,
+            spilled=node.spilled_to_disk, shared_read=node.shared_read,
+            rows_removed_by_filter=node.rows_removed_by_filter,
+            heap_fetches=node.heap_fetches))
+    return out
+
+
+def rollups(plan: Plan, metrics: list[NodeMetrics]) -> dict:
+    timed = [m for m in metrics if m.self_time is not None]
+    top = sorted(timed, key=lambda m: m.self_time, reverse=True)[:5]
+    errors = [m.estimation_error for m in metrics if m.estimation_error is not None]
+    return {
+        "execution_time_ms": plan.execution_time,
+        "planning_time_ms": plan.planning_time,
+        "has_actuals": plan.has_actuals,
+        "node_count": len(metrics),
+        "max_depth": max((len(m.path) for m in metrics), default=0),
+        "max_estimation_error": max(errors) if errors else None,
+        "spilled_to_disk": any(m.spilled for m in metrics),
+        "total_shared_read_blocks": sum(m.shared_read for m in metrics),
+        "top_self_time": [
+            {"label": m.label, "self_time_ms": m.self_time, "pct_self": m.pct_self}
+            for m in top
+        ],
+    }