feat(schema): drag a DB/table into the data pane for a lineage graph

[BorisTyshkevich]

What

Drag a database or table row from the schema sidebar onto the results pane to render a graph of ClickHouse object relationships — not generic foreign keys, but engine-specific lineage:

• materialized views — feeds from sources, writes to the target
• views — reads their sources
• dictionaries — dict from a source table (or an external leaf for non-CH sources)
• Distributed / Buffer / Merge — engine-arg references to backing tables

Drag a DB → whole-DB lineage (isolated tables with no relationships are pruned so the lineage is the focus); drag a table → its 1-hop neighbourhood. Click any node to re-centre on it; Expand for a fullscreen pan/zoom view (same controls as the pipeline graph). Nodes are kind-coloured with a legend; edges are coloured + labelled by relationship.

How discovery works (structured-first, parse-fallback)

The helpful system.tables columns are build-dependent, so the loader prefers structured columns (dependencies_table / loading_dependencies_* / system.dictionaries.source) when populated, and otherwise lets ClickHouse parse the SQL via EXPLAIN AST (query sources) plus light regex on create_table_query (TO target) and engine_full (Distributed/Buffer/Merge args). EXPLAIN AST's TableIdentifier lines are cross-checked against real objects, dropping CTE/alias false-positives.

This was validated empirically: on otel (Altinity-antalya CH 26.3.10) a real MV has no target_* column and empty dependencies_* — a pure-structured approach would render nothing there, so the EXPLAIN AST + create-query parsing path is required for the builds we deploy to.

Verified live

Deployed the branch build to otel and dragged bentoclick onto the results pane:

dashboards_raw —feeds→ dashboards_mv —writes→ dashboards_tok —reads→ dashboards (the writes target came from parsing TO, the feeds/reads from EXPLAIN AST — the parse-fallback path). Click-to-expand on dashboards_mv correctly re-focused to its 1-hop neighbourhood. Kind-colouring (purple MV, teal views, blue dictionaries) and the legend render correctly in both Chrome and Firefox (verified color-mix resolves, not the dark base).

Layers / tests

• src/core/schema-graph.js (NEW, pure, 100%-covered) — all parsers + buildSchemaGraph
• src/net/ch-client.js — loadSchemaLineage (scope query + per-view/MV EXPLAIN AST)
• src/core/dot-layout.js — pass node kind + edge label through the dagre seam
• src/ui/explain-graph.js — extracted renderGraphSvg; buildSchemaSvg; generalized fullscreen overlay; renderSchemaGraph + legend + click-to-expand
• src/ui/results.js, schema.js, editor.js, app.js — render dispatch, second SCHEMA_GRAPH_MIME drag payload, results-region drop target + showSchemaGraph action
• styles.css — kind-coloured nodes/edges + legend (node-kind rules scoped under .explain-graph so the kind fill beats the base — this was a real bug caught in live testing)
• tests — schema-graph unit, e2e harness + spec, plus results/app/schema/ch-client/explain-graph specs. 852 tests pass; per-file coverage gate holds.

Notes for review

• Isolated-node pruning on DB focus is a product decision: a DB with 22 tables but only 8 in lineage rendered a useless wide strip of singletons, so degree-0 nodes are dropped when there is lineage (a DB with no relationships still shows its tables). Easy to revert if you'd rather see everything.
• Column cards inside nodes (à la play.clickhouse.com/schema), an insert heat-map, and refreshable-MV badges are intentionally deferred to fast-follow (see the plan).
• e2e (tests/e2e/schema-graph.spec.js) runs in CI / locally — Playwright browsers can't launch in the dev sandbox (SIGTRAP), which also affects the pre-existing pipeline spec; the Firefox render path was instead verified against the live harness via the agent browser.

🤖 Generated with Claude Code