mdbkit 0.1.0__py3-none-any.whl

mdbkit/explain.py

@@ -0,0 +1,244 @@
+"""Explain-plan analyzer for `mdbkit explain`.
+
+Reads a saved explain output (JSON produced by
+`db.coll.find(...).explain("executionStats")` in mongosh, or exported from
+Compass) and answers the question every DBA asks: *why is this query slow,
+and what would fix it?*
+
+Handles classic and SBE (6.0+) plan shapes, aggregate explains ($cursor),
+and sharded winning plans. Reuses the same deterministic advisor as
+`mdbkit advise`, so the recommendation logic is identical everywhere.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from .advisor import Recommendation, advise
+from .analysis import QueryAggregator
+from .parser import LogEntry
+
+
+@dataclass
+class ExplainReport:
+    ns: str
+    stage_chain: List[str]
+    collscan: bool
+    blocking_sort: bool
+    indexes_used: List[str]
+    n_returned: int
+    keys_examined: int
+    docs_examined: int
+    exec_ms: int
+    rejected_plans: int
+    verdicts: List[str] = field(default_factory=list)
+    recommendation: Optional[Recommendation] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "ns": self.ns,
+            "stages": self.stage_chain,
+            "collscan": self.collscan,
+            "blockingSort": self.blocking_sort,
+            "indexesUsed": self.indexes_used,
+            "nReturned": self.n_returned,
+            "keysExamined": self.keys_examined,
+            "docsExamined": self.docs_examined,
+            "executionTimeMillis": self.exec_ms,
+            "rejectedPlans": self.rejected_plans,
+            "verdicts": self.verdicts,
+            "recommendation": self.recommendation.to_dict() if self.recommendation else None,
+        }
+
+
+def _collect_stages(plan, out: List[dict], depth: int = 0):
+    """Walk a winning plan tree collecting stage docs (classic, SBE, sharded)."""
+    if depth > 20 or not isinstance(plan, dict):
+        return
+    if plan.get("stage"):
+        out.append(plan)
+    for key in ("queryPlan", "winningPlan", "inputStage", "innerStage",
+                "outerStage", "thenStage", "elseStage"):
+        if key in plan:
+            _collect_stages(plan[key], out, depth + 1)
+    for key in ("inputStages", "shards"):
+        subs = plan.get(key)
+        if isinstance(subs, list):
+            for sub in subs:
+                _collect_stages(sub, out, depth + 1)
+
+
+def _find_query_planner(doc: dict) -> Tuple[dict, dict]:
+    """Locate queryPlanner + executionStats in find or aggregate explains."""
+    if "queryPlanner" in doc:
+        return doc.get("queryPlanner") or {}, doc.get("executionStats") or {}
+    for stage in doc.get("stages", []) or []:
+        if not isinstance(stage, dict):
+            continue
+        cursor = stage.get("$cursor") or stage.get("$geoNearCursor")
+        if isinstance(cursor, dict) and "queryPlanner" in cursor:
+            return cursor.get("queryPlanner") or {}, cursor.get("executionStats") or {}
+    return {}, {}
+
+
+def load_explain(path: str) -> dict:
+    with open(path, "r", encoding="utf-8") as fh:
+        text = fh.read()
+    try:
+        doc = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            "This file is not valid JSON. Legacy mongo-shell explain output "
+            "contains constructors like NumberLong(...) that are not JSON; "
+            "re-export with mongosh (e.g. "
+            "`EJSON.stringify(db.coll.find(...).explain('executionStats'))`) "
+            "or use Compass's JSON export."
+        ) from exc
+    if isinstance(doc, list) and doc:
+        doc = doc[0]
+    if not isinstance(doc, dict):
+        raise ValueError("Expected a single explain JSON document.")
+    return doc
+
+
+def analyze_explain(doc: dict, indexes=None, schema=None) -> ExplainReport:
+    qp, es_inner = _find_query_planner(doc)
+    es = doc.get("executionStats") or es_inner or {}
+    winning = qp.get("winningPlan") or {}
+
+    stages: List[dict] = []
+    _collect_stages(winning, stages)
+    chain = [s.get("stage", "?") for s in stages]
+
+    collscan = any(s.get("stage") == "COLLSCAN" for s in stages)
+    blocking_sort = any(s.get("stage") == "SORT" for s in stages)
+    fetch = any(s.get("stage") == "FETCH" for s in stages)
+
+    indexes_used: List[str] = []
+    for s in stages:
+        if s.get("stage") in ("IXSCAN", "DISTINCT_SCAN", "COUNT_SCAN"):
+            name = s.get("indexName") or json.dumps(s.get("keyPattern", {}))
+            if name and name not in indexes_used:
+                indexes_used.append(name)
+
+    n_returned = int(es.get("nReturned", 0) or 0)
+    keys_examined = int(es.get("totalKeysExamined", 0) or 0)
+    docs_examined = int(es.get("totalDocsExamined", 0) or 0)
+    exec_ms = int(es.get("executionTimeMillis", 0) or 0)
+    rejected = len(qp.get("rejectedPlans") or [])
+
+    verdicts: List[str] = []
+    if collscan:
+        verdicts.append(
+            f"Full collection scan: examined {docs_examined:,} documents to "
+            f"return {n_returned:,}. An index on the filter fields would let "
+            "MongoDB skip straight to matching documents."
+        )
+    if blocking_sort:
+        verdicts.append(
+            "In-memory (blocking) SORT stage: results are sorted after "
+            "retrieval instead of being read from an index in order. Sorts "
+            "over 100MB abort the query unless allowDiskUse is set."
+        )
+    if not collscan and indexes_used:
+        if n_returned and docs_examined > 10 * n_returned:
+            verdicts.append(
+                f"Index used ({', '.join(indexes_used)}) but it is weakly "
+                f"selective here: {docs_examined:,} docs fetched for "
+                f"{n_returned:,} returned. The index may match the filter "
+                "only partially."
+            )
+        elif keys_examined and n_returned and keys_examined > 10 * n_returned:
+            verdicts.append(
+                f"Index scanned many more keys ({keys_examined:,}) than "
+                f"documents returned ({n_returned:,}); check field order vs "
+                "the ESR guideline."
+            )
+        else:
+            verdicts.append(
+                f"Index used efficiently ({', '.join(indexes_used)}): "
+                f"keysExamined={keys_examined:,}, "
+                f"docsExamined={docs_examined:,}, nReturned={n_returned:,}."
+            )
+    if indexes_used and not fetch and docs_examined == 0 and n_returned:
+        verdicts.append(
+            "Covered query: answered entirely from the index without touching "
+            "documents. This is as good as it gets."
+        )
+    if rejected:
+        verdicts.append(
+            f"{rejected} alternative plan(s) were considered and rejected — "
+            "if plan choice flaps, look at rejectedPlans in the raw output."
+        )
+    if not verdicts:
+        verdicts.append("No obvious pathology detected in this plan.")
+
+    # Reuse the advisor for a recommendation when the plan needs help.
+    recommendation = None
+    command = doc.get("command") if isinstance(doc.get("command"), dict) else {}
+    ns = qp.get("namespace") or (command.get("$db", "") + "." +
+                                 str(command.get("find") or
+                                     command.get("aggregate") or "")).strip(".")
+    if (collscan or blocking_sort or
+            (n_returned and docs_examined > 10 * n_returned)) and command:
+        entry = LogEntry(
+            ts=None, severity="I", component="COMMAND", msg_id=51803,
+            ctx="explain", msg="Slow query",
+            attr={
+                "ns": ns,
+                "command": command,
+                "planSummary": "COLLSCAN" if collscan else "IXSCAN",
+                "docsExamined": docs_examined,
+                "nreturned": n_returned,
+                "hasSortStage": blocking_sort,
+                "durationMillis": exec_ms,
+            },
+        )
+        agg = QueryAggregator()
+        agg.consume(entry)
+        recs = advise(agg.results(), indexes=indexes, schema=schema)
+        if recs:
+            recommendation = recs[0]
+
+    return ExplainReport(
+        ns=ns or "(unknown)",
+        stage_chain=chain,
+        collscan=collscan,
+        blocking_sort=blocking_sort,
+        indexes_used=indexes_used,
+        n_returned=n_returned,
+        keys_examined=keys_examined,
+        docs_examined=docs_examined,
+        exec_ms=exec_ms,
+        rejected_plans=rejected,
+        verdicts=verdicts,
+        recommendation=recommendation,
+    )
+
+
+def render_explain(report: ExplainReport) -> str:
+    parts = ["== mdbkit explain ==", ""]
+    parts.append(f"namespace : {report.ns}")
+    parts.append(f"plan      : {' -> '.join(report.stage_chain) or '(no stages found)'}")
+    if report.indexes_used:
+        parts.append(f"index(es) : {', '.join(report.indexes_used)}")
+    parts.append(
+        f"stats     : nReturned={report.n_returned:,}  "
+        f"keysExamined={report.keys_examined:,}  "
+        f"docsExamined={report.docs_examined:,}  "
+        f"time={report.exec_ms:,} ms"
+    )
+    parts.append("")
+    for v in report.verdicts:
+        parts.append(f"* {v}")
+    rec = report.recommendation
+    if rec:
+        parts.append("")
+        parts.append(f"candidate index ({rec.confidence.upper()} confidence): "
+                     f"{rec.candidate_str()}")
+        for c in rec.caveats:
+            parts.append(f"  caveat: {c}")
+        parts.append(f"  validate: {rec.validation}")
+    return "\n".join(parts)

mdbkit/filtering.py

@@ -0,0 +1,55 @@
+"""`mdbkit filter` — the mlogfilter successor.
+
+Streams matching raw logv2 lines to stdout so output stays valid JSON logs
+and can be chained: `mdbkit filter f.log --slow 500 | mdbkit queries -`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from .parser import LogEntry
+
+
+class Filter:
+    def __init__(
+        self,
+        component: Optional[str] = None,
+        severity: Optional[str] = None,
+        namespace: Optional[str] = None,
+        slow_ms: Optional[int] = None,
+        ts_from: Optional[datetime] = None,
+        ts_to: Optional[datetime] = None,
+        msg_contains: Optional[str] = None,
+    ):
+        self.component = component.upper() if component else None
+        self.severity = severity.upper() if severity else None
+        self.namespace = namespace
+        self.slow_ms = slow_ms
+        self.ts_from = ts_from
+        self.ts_to = ts_to
+        self.msg_contains = msg_contains.lower() if msg_contains else None
+
+    def matches(self, entry: LogEntry) -> bool:
+        if self.component and entry.component.upper() != self.component:
+            return False
+        if self.severity and entry.severity.upper() != self.severity:
+            return False
+        if self.namespace and entry.attr.get("ns") != self.namespace:
+            return False
+        if self.slow_ms is not None:
+            if int(entry.attr.get("durationMillis", -1) or -1) < self.slow_ms:
+                return False
+        if self.ts_from and (entry.ts is None or entry.ts < self.ts_from):
+            return False
+        if self.ts_to and (entry.ts is None or entry.ts > self.ts_to):
+            return False
+        if self.msg_contains and self.msg_contains not in entry.msg.lower():
+            return False
+        return True
+
+
+def parse_when(value: str) -> datetime:
+    """Parse a --from/--to value (ISO 8601, 'Z' allowed)."""
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))

mdbkit/parser.py

@@ -0,0 +1,149 @@
+"""Parser for MongoDB structured JSON logs (logv2, MongoDB 4.4+).
+
+Every log line since MongoDB 4.4 is a single JSON document:
+
+    {"t":{"$date":"..."},"s":"I","c":"COMMAND","id":51803,"ctx":"conn42",
+     "msg":"Slow query","attr":{...}}
+
+This module parses those lines defensively: real-world logs contain
+truncated lines, interleaved plain-text output, and rotated .gz files.
+Everything here is offline and dependency-free by design.
+"""
+
+from __future__ import annotations
+
+import gzip
+import io
+import json
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Iterator, Optional
+
+# Well-known logv2 message ids we care about.
+ID_SLOW_QUERY = 51803
+ID_CONN_ACCEPTED = 22943
+ID_CONN_ENDED = 22944
+ID_CLIENT_METADATA = 51800
+ID_STARTUP = 4615611
+ID_BUILD_INFO = 23403
+
+
+@dataclass
+class LogEntry:
+    """One parsed logv2 line."""
+
+    ts: Optional[datetime]
+    severity: str
+    component: str
+    msg_id: int
+    ctx: str
+    msg: str
+    attr: dict = field(default_factory=dict)
+    raw: str = ""
+
+    @property
+    def is_slow_query(self) -> bool:
+        return self.msg_id == ID_SLOW_QUERY or self.msg == "Slow query"
+
+
+@dataclass
+class ParseStats:
+    """Bookkeeping for how much of the file we understood."""
+
+    total_lines: int = 0
+    parsed: int = 0
+    unparsed: int = 0
+    first_ts: Optional[datetime] = None
+    last_ts: Optional[datetime] = None
+
+    @property
+    def unparsed_ratio(self) -> float:
+        return self.unparsed / self.total_lines if self.total_lines else 0.0
+
+
+def _parse_ts(value) -> Optional[datetime]:
+    """Parse a logv2 timestamp: {"$date": "ISO"} or {"$date": {"$numberLong": ms}}."""
+    if isinstance(value, dict):
+        value = value.get("$date", value)
+    if isinstance(value, dict):  # {"$numberLong": "..."} (epoch millis)
+        millis = value.get("$numberLong")
+        if millis is not None:
+            try:
+                return datetime.fromtimestamp(int(millis) / 1000.0).astimezone()
+            except (ValueError, OSError):
+                return None
+    if isinstance(value, str):
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return None
+
+
+def parse_line(line: str) -> Optional[LogEntry]:
+    """Parse one line. Returns None for anything that isn't a logv2 JSON doc."""
+    line = line.strip()
+    if not line or not line.startswith("{"):
+        return None
+    try:
+        doc = json.loads(line)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(doc, dict) or "s" not in doc or "c" not in doc:
+        return None
+    return LogEntry(
+        ts=_parse_ts(doc.get("t")),
+        severity=str(doc.get("s", "")),
+        component=str(doc.get("c", "")),
+        msg_id=int(doc.get("id", 0) or 0),
+        ctx=str(doc.get("ctx", "")),
+        msg=str(doc.get("msg", "")),
+        attr=doc.get("attr") or {},
+        raw=line,
+    )
+
+
+def open_log(path: str) -> io.TextIOBase:
+    """Open a log file, stdin ('-'), or a rotated .gz transparently."""
+    if path == "-":
+        return sys.stdin
+    if path.endswith(".gz"):
+        return io.TextIOWrapper(gzip.open(path, "rb"), encoding="utf-8", errors="replace")
+    # Sniff gzip magic bytes even without the extension.
+    with open(path, "rb") as probe:
+        magic = probe.read(2)
+    if magic == b"\x1f\x8b":
+        return io.TextIOWrapper(gzip.open(path, "rb"), encoding="utf-8", errors="replace")
+    return open(path, "r", encoding="utf-8", errors="replace")
+
+
+def iter_entries(path: str, stats: Optional[ParseStats] = None) -> Iterator[LogEntry]:
+    """Stream LogEntry objects from a file, tracking parse stats if given."""
+    handle = open_log(path)
+    try:
+        for line in handle:
+            if stats is not None:
+                stats.total_lines += 1
+            entry = parse_line(line)
+            if entry is None:
+                if stats is not None and line.strip():
+                    stats.unparsed += 1
+                continue
+            if stats is not None:
+                stats.parsed += 1
+                if entry.ts is not None:
+                    if stats.first_ts is None:
+                        stats.first_ts = entry.ts
+                    stats.last_ts = entry.ts
+            yield entry
+    finally:
+        if handle is not sys.stdin:
+            handle.close()
+
+
+PRE_44_HINT = (
+    "Most lines in this file are not structured JSON. This looks like a "
+    "pre-4.4 MongoDB log (plain text format). mdbkit targets MongoDB 4.4+ "
+    "structured logs; for older logs, the original mtools still works."
+)

mdbkit/render.py

@@ -0,0 +1,141 @@
+"""Plain-text rendering. No third-party dependencies, pipe-friendly output."""
+
+from __future__ import annotations
+
+import json
+from typing import List, Sequence
+
+from .advisor import Recommendation
+from .analysis import ConnectionReport, LogSummary, ShapeStats
+from .parser import ParseStats
+
+
+def dump_json(obj) -> str:
+    return json.dumps(obj, indent=2, default=str)
+
+
+def _table(headers: Sequence[str], rows: List[Sequence[str]]) -> str:
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(str(cell)))
+    fmt = "  ".join(f"{{:<{w}}}" for w in widths)
+    lines = [fmt.format(*headers), fmt.format(*("-" * w for w in widths))]
+    lines += [fmt.format(*(str(c) for c in row)) for row in rows]
+    return "\n".join(lines)
+
+
+def _ms(v: float) -> str:
+    if v >= 60_000:
+        return f"{v/60_000:.1f}m"
+    if v >= 1_000:
+        return f"{v/1_000:.1f}s"
+    return f"{int(v)}ms"
+
+
+def render_parse_stats(stats: ParseStats) -> str:
+    span = ""
+    if stats.first_ts and stats.last_ts:
+        span = f"  span: {stats.first_ts.isoformat()} -> {stats.last_ts.isoformat()}"
+    return (
+        f"lines: {stats.total_lines:,}  parsed: {stats.parsed:,}  "
+        f"unparsed: {stats.unparsed:,}{span}"
+    )
+
+
+def render_summary(summary: LogSummary, stats: ParseStats) -> str:
+    parts = ["== mdbkit loginfo ==", render_parse_stats(stats), ""]
+    parts.append(f"server version(s): {', '.join(summary.versions) or 'not found in log'}")
+    if summary.host_info:
+        parts.append(f"host: {', '.join(dict.fromkeys(summary.host_info))}")
+    parts.append(f"restarts/startups seen: {summary.startups}")
+    parts.append(f"connections accepted: {summary.connections_accepted:,}")
+    parts.append(
+        f"slow queries logged: {summary.slow_queries:,}"
+        + (f" (slowest {_ms(summary.slowest_ms)})" if summary.slow_queries else "")
+    )
+    parts.append(f"warnings: {summary.warnings:,}   errors: {summary.errors:,}")
+    parts.append("")
+    top = summary.component_counts.most_common(8)
+    if top:
+        parts.append(_table(["component", "lines"], [(c, f"{n:,}") for c, n in top]))
+    return "\n".join(parts)
+
+
+def render_queries(results: List[ShapeStats], stats: ParseStats) -> str:
+    parts = ["== mdbkit queries (slow query shapes) ==", render_parse_stats(stats), ""]
+    if not results:
+        parts.append("No slow queries found. (mongod logs operations exceeding "
+                      "slowms, default 100 ms; lower slowms or enable profiling "
+                      "to capture more.)")
+        return "\n".join(parts)
+    rows = []
+    for s in results:
+        flags = []
+        if s.collscan:
+            flags.append("COLLSCAN")
+        if s.in_memory_sort:
+            flags.append("SORT")
+        rows.append((
+            s.shape.ns,
+            s.shape.operation,
+            s.count,
+            _ms(s.total_ms),
+            _ms(s.mean_ms),
+            _ms(s.max_ms),
+            f"{s.scan_ratio:.0f}:1" if s.n_returned else "-",
+            ",".join(flags) or "-",
+            s.shape.pretty()[:70],
+        ))
+    parts.append(_table(
+        ["namespace", "op", "count", "total", "mean", "max", "scan", "flags", "shape"],
+        rows,
+    ))
+    parts.append("")
+    parts.append("scan = docsExamined per returned doc. COLLSCAN/SORT flags mean an "
+                 "index is likely missing; run `mdbkit advise` for candidates.")
+    return "\n".join(parts)
+
+
+def render_connections(report: ConnectionReport, stats: ParseStats) -> str:
+    parts = ["== mdbkit connections ==", render_parse_stats(stats), ""]
+    d = report.to_dict()
+    parts.append(
+        f"accepted: {d['totalAccepted']:,}   ended: {d['totalEnded']:,}   "
+        f"peak concurrent (as logged): {d['peakConnectionCount']:,}"
+    )
+    if d["byIp"]:
+        parts.append("")
+        parts.append(_table(
+            ["source ip", "accepted", "ended"],
+            [(r["ip"], r["accepted"], r["ended"]) for r in d["byIp"][:20]],
+        ))
+    if d["appNames"]:
+        parts.append("")
+        parts.append(_table(["appName", "handshakes"], list(d["appNames"].items())[:15]))
+    return "\n".join(parts)
+
+
+def render_recommendations(recs: List[Recommendation], stats: ParseStats) -> str:
+    parts = ["== mdbkit advise (candidate indexes) ==", render_parse_stats(stats), ""]
+    if not recs:
+        parts.append("No index candidates: no slow query shapes showed COLLSCAN, "
+                      "in-memory sorts, or high scan ratios. Good sign — or the "
+                      "log window is too quiet to judge.")
+        return "\n".join(parts)
+    for i, rec in enumerate(recs, 1):
+        parts.append(f"[{i}] {rec.ns}  —  confidence: {rec.confidence.upper()}")
+        parts.append(f"    query shape : {rec.shape}")
+        parts.append(f"    candidate   : {rec.candidate_str()}")
+        if rec.covered_by:
+            parts.append(f"    NOTE        : may already be covered by existing "
+                         f"index '{rec.covered_by}' — investigate before creating")
+        for e in rec.evidence:
+            parts.append(f"    evidence    : {e}")
+        for c in rec.caveats:
+            parts.append(f"    caveat      : {c}")
+        parts.append(f"    validate    : {rec.validation}")
+        parts.append("")
+    parts.append("These are CANDIDATES, not commands. Review, test on staging, and "
+                  "watch write latency and index build impact before production.")
+    return "\n".join(parts)

mdbkit/scripts.py

@@ -0,0 +1,69 @@
+"""mongosh export scripts, printed by `mdbkit export-script`.
+
+mdbkit never connects to a database. Instead it prints small mongosh
+scripts the operator runs themselves, producing JSON files that can be
+fed back via --schema / --indexes. The operator sees exactly what runs.
+"""
+
+SCHEMA_SCRIPT = r"""// mdbkit schema export -- run with:
+//   mongosh --quiet "mongodb://HOST/DB" this_file.js > schema.json
+// Samples documents per collection to learn field paths and types.
+// Reads only; writes nothing; literal values are NOT exported (types only).
+const SAMPLE = 100;      // docs sampled per collection
+const MAX_DEPTH = 3;     // nested path depth
+const out = { db: db.getName(), generatedAt: new Date().toISOString(),
+              sampleSize: SAMPLE, collections: {} };
+
+function typeName(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  if (v instanceof Date) return "date";
+  if (v && v._bsontype === "ObjectId") return "objectId";
+  if (typeof v === "object") return "object";
+  if (typeof v === "number") return Number.isInteger(v) ? "int" : "double";
+  return typeof v; // string, boolean -> bool below
+}
+
+function record(fields, path, v, depth) {
+  let t = typeName(v);
+  if (t === "boolean") t = "bool";
+  if (!fields[path]) fields[path] = { types: new Set(), count: 0 };
+  fields[path].types.add(t);
+  fields[path].count += 1;
+  if (depth >= MAX_DEPTH) return;
+  if (t === "object") {
+    for (const k of Object.keys(v)) record(fields, path + "." + k, v[k], depth + 1);
+  } else if (t === "array" && v.length > 0 && typeof v[0] === "object"
+             && v[0] !== null && !Array.isArray(v[0])) {
+    for (const k of Object.keys(v[0])) record(fields, path + "." + k, v[0][k], depth + 1);
+  }
+}
+
+db.getCollectionNames().filter(c => !c.startsWith("system.")).forEach(coll => {
+  const fields = {};
+  let n = 0;
+  db.getCollection(coll).aggregate([{ $sample: { size: SAMPLE } }]).forEach(doc => {
+    n += 1;
+    for (const k of Object.keys(doc)) record(fields, k, doc[k], 1);
+  });
+  const serialized = {};
+  for (const [path, info] of Object.entries(fields)) {
+    serialized[path] = { types: Array.from(info.types).sort(),
+                         presence: n ? Math.round(100 * info.count / n) / 100 : 0 };
+  }
+  out.collections[coll] = { sampleSize: n, fields: serialized };
+});
+
+print(JSON.stringify(out));
+"""
+
+INDEXES_SCRIPT = r"""// mdbkit index export -- run with:
+//   mongosh --quiet "mongodb://HOST/DB" this_file.js > indexes.json
+// Exports index metadata only (getIndexes). Reads nothing else.
+const out = { db: db.getName(), generatedAt: new Date().toISOString(),
+              collections: {} };
+db.getCollectionNames().filter(c => !c.startsWith("system.")).forEach(coll => {
+  out.collections[coll] = db.getCollection(coll).getIndexes();
+});
+print(JSON.stringify(out));
+"""