TS Object Model Erd

ThoughtSpot: Model ERD

Render a Model into a single self-contained HTML ERD. Read-only — never modifies the source model.

When to use this skill:

• You want to visualise or diagram the structure of a ThoughtSpot Model
• You need to review joins, cardinality, column layout, or RLS before making changes
• You want to share a Model's structure with someone who doesn't have ThoughtSpot access
• You need a visual reference while coaching or auditing a Model

Relationship to other skills:

Ask one question at a time for dependent decisions. Batch independent questions into a single prompt to cut round-trips.

References

Prerequisites

• Python 3.9+ with pyyaml (pip install pyyaml)
• For live export: a ThoughtSpot profile (/ts-profile-thoughtspot) + the ts CLI
• For a source semantic definition (Step 1.5): the ts CLI only — no ThoughtSpot profile and no warehouse connection are needed

Step 0 — Overview (confirm before starting)

On skill invocation, display this plan before doing any work:

ts-object-model-erd — render a Model into a self-contained HTML ERD. Read-only — never modifies the source model.

Steps

1. Choose source ....................................... ask 1.5 (Source definition) Convert offline, then render ... ask/auto
2. (Live) Authenticate + select models ................ ask/auto
3. Read or export TML .................................. auto
4. Synthesize AI-analysis corpus ...................... auto
5. Render ERD .......................................... auto
6. Open / share ........................................ done

Options

Confirm the user wants to proceed before starting Step 1.

Step 1 — Choose source

Ask: (A) Local TML files or folder, (B) Live ThoughtSpot instance, or (C) A source semantic definition (a Snowflake Semantic View or a Databricks Metric View)?

• A — Files: ask for the path(s) to the TML files or directory. Skip to Step 3.
• B — Live: proceed to Step 2.
• C — Source definition: proceed to Step 1.5.

Step 1.5 — (Source definition only) Convert, then render

The ERD renders ThoughtSpot TML, so convert first. This runs fully offline — no ThoughtSpot instance, no warehouse, no profile — because --tables auto derives the alias→table map from the parse output instead of introspecting a warehouse.

Ask for the path to the source file, then run the pair of commands for its format and continue to Step 5 with the emitted .model.tml.

Snowflake Semantic View (a CREATE SEMANTIC VIEW DDL file — get one with GET_DDL('SEMANTIC_VIEW', '<fqn>') if the user only has the view name):

ts snowflake parse-sv "{ddl_file}" -o parsed.json
ts snowflake translate-formulas -i parsed.json -o translated.json
ts snowflake build-model -p parsed.json -t translated.json \
    --tables auto -n "{model_name}" -o tml_out --sv-fqn "{source_fqn}"

Databricks Metric View (the Metric View YAML):

ts databricks parse-mv "{mv_yaml}" -o parsed.json
ts databricks translate-formulas -i parsed.json -o translated.json --tables auto
ts databricks build-model -p parsed.json -t translated.json \
    --tables auto -n "{model_name}" -o tml_out --mv-fqn "{source_fqn}"

Note the asymmetry: Databricks needs --tables auto on both commands because its expressions are dot-paths that resolve through the map, while Snowflake needs it only at build-model.

Report what the conversion says. Both commands print a JSON summary and send diagnostics to stderr. A SKIPPED line means a measure or dimension did not survive translation and will be absent from the diagram — surface those to the user rather than letting the ERD imply the source had nothing there. On the Databricks side a WARNING: '<path>' has no table FQN means a sql_query source was labelled with its alias, because a real conversion would build a SQL View there.

Say what the diagram is. An ERD built this way shows the ThoughtSpot Model the source would convert to, not the source's native shape. For a Semantic View that is close to 1:1; state it anyway when sharing the file. --sv-fqn / --mv-fqn writes the source FQN into the model description, so the provenance travels with the diagram.

Do not import this model. --tables auto looks nothing up, so the map carries no warehouse GUIDs; both commands refuse --profile for that reason. Converting for real is a different job with different steps (table registration, connection choice, review gates) — route the user to /ts-convert-from-snowflake-sv or /ts-convert-from-databricks-mv.

Other sources (Tableau, Power BI, Qlik, Sisense, Looker) are not wired into this step. Their conversion invents the table layer from extracts and makes reconcile and name-mapping decisions, so a diagram-only run would stub out exactly the choices that determine what the picture looks like. To diagram one of those, run its converter properly first and render the resulting TML through option (A).

Step 2 — (Live only) Authenticate, enumerate, select

1. Read ~/.claude/thoughtspot-profiles.json. If missing or empty, run /ts-profile-thoughtspot.
2. List Models:

   ts metadata search --subtype ONE_TO_ONE_LOGICAL --all --profile "{profile}"
   

3. Show the user the list. Let them pick one or more models. Confirm selection before export.

Step 3 — Read or export TML

• Files path: note the folder/paths provided in Step 1.

• Live path: for each selected model, export it with its associated tables and redirect the JSON straight to a file:

  ts tml export "{model_guid}" --fqn --associated --profile "{profile}" > export.json
  

  --associated pulls the Table TMLs needed for join cardinality, join origin, RLS rules, and join keys.

  ts tml export writes a single JSON array to stdout (one {edoc} object per exported object). Feed that file directly to the builder in Step 5 — do not hand-split it into per-object .tml files. build_erd.py ingests the export JSON as-is and routes each object to model/table by its TML content. Multiple models: pass several GUIDs to one ts tml export call, or pass several export*.json files to the builder.

Step 4 — Synthesize the AI-analysis corpus (optional but recommended)

Models rarely define a business-context corpus (domain, objectives, audience, business questions). Synthesize one by reasoning over the model definition — table and column names, per-column properties.ai_context, properties.synonyms, measure aggregations, formula expressions, joins, and RLS. This is a judgment task for you (the agent); do not try to derive it with a heuristic script.

Write the result to a sidecar JSON keyed by model guid (or name):

{
  "<model-guid>": {
    "ai_analysis": {
      "domain": "one-paragraph description of the business domain the model serves",
      "objectives": ["what analysis it's built for", "..."],
      "personas": ["who uses it", "..."],
      "questions": ["representative business questions it answers", "..."]
    },
    "ai_instructions": ["semantic rules grounded in the model, e.g. 'Amount is the primary revenue measure'", "..."]
  }
}

Ground every entry in the actual model: cite real measures, note semi-additive or averaged aggregations, and lift genuine guidance out of ai_context (e.g. day-grain date handling). This step is read-only — the corpus enriches the ERD only and is never written back to the source model.

Step 5 — Render

Run — pass the Step 3 export.json (or a directory / individual .tml files) directly:

python3 agents/cli/ts-object-model-erd/build_erd.py export.json --out model_erd.html

src accepts, in any mix: a ts tml export JSON dump, individual .tml/.yaml files, or a directory of them. Model vs. table is decided by TML content, so no naming convention or split step is required.

Add --ai-analysis <corpus.json> to inject the Step 4 corpus into the ERD's Model domain / Key objectives / Audience / Business questions / AI instructions sections. Add --redact-rls if the user wants to hide RLS expressions for external sharing. Add --max-models N to change the model cap.

If the source contains no model (e.g. only table TMLs), the builder exits non-zero with a clear message rather than writing an empty diagram — re-export with --associated and confirm the model GUID.

Report any degraded-fidelity or model-cap log lines to the user. Degraded fidelity means Table TMLs were missing for some joins — the ERD still renders structure, but cardinality, join type, join origin, RLS, and join keys are omitted for those joins.

Step 6 — Open / share

Open model_erd.html in a browser. The file is fully self-contained — share the single HTML file; no ThoughtSpot login required to view.

ERD features:

• Four layouts: Organic, Star, Layered →, Layered ↓
• Two notations: Arrow (ThoughtSpot-style), Crow's foot (cardinality)
• Column modes: Collapsed, Join keys, Flagged only, All columns
• Focus mode: click a table to highlight its neighbourhood; shift-click to compare two tables
• RLS overlay: toggle to see secured subgraph
• Findings overlay: toggle to see structural findings
• Drag to reposition tables; positions auto-save in localStorage
• Multi-model switcher (when multiple models rendered)
• Navigation: drag or scroll to pan; pinch / ⌘-scroll (Ctrl-scroll on Windows) to zoom; arrow keys pan, +/- zoom, 0 fits (to the focused neighbourhood if a table is focused, otherwise the whole model) — built for large models (verified on a 79-table export) where the default fit would otherwise be microscopic
• Minimap: always-on overview in the bottom-right corner with a viewport rectangle; click or drag it to jump anywhere in the model; collapsible, and the collapsed/expanded state persists across reloads
• Search zooms to a readable level (never leaves you at a microscopic fit scale)
• Semantic zoom (overview legibility): below 0.5× zoom, tables render as bold, color-coded overview blocks (solid saturated fill by kind, crisp non-scaling border, centered title) instead of full column cards — so a large model's fit view (e.g. 79 tables at ~0.12×) still reads as distinct, outlined regions rather than faint white boxes. Node and edge borders no longer scale away to invisibility at any zoom level. Crosses back to full detail cards above the threshold; state borders (secured/RLS/ severity/focus), click-to-focus, drag, and the minimap all keep working at either scale.
• Notes: attach a free-text note to any table or join from its inspector panel — Save and Delete give immediate feedback (a self-dismissing "Saved ✓" / "Note deleted" confirmation, with Delete reachable in the same session, no reload needed). A Notes filter chip highlights every noted object — including at overview/LOD zoom, where the note badge itself isn't drawn — and disables itself automatically when no notes exist (enables the instant a note is saved, including notes baked into a shared HTML export). A Review notes button lists every note at once (table/join tag, or "not in model" for a note whose object was since renamed or removed); clicking a row jumps to and centers that object, and each row can be deleted inline.
• Group by (subject areas): a Group by selector colors tables into subject areas via one of three selectable strategies — Name prefix (source-system naming, e.g. SFDC_*/MIXPANEL_*), Graph cluster (community detection on the join graph, for models whose naming is messy but whose joins reflect domains), or Fact neighbourhood (each fact + the dimensions nearest to it). A group shows as a colored accent stripe on each node (and tints the overview/LOD block), with a legend you can click to highlight a single group. Non-destructive — grouping only recolors; it never changes the layout, and composes with the fact/dim fill and RLS/focus borders. Different models suit different strategies; pick the one that reads best.

Notes

• RLS rules, join cardinality, join type, and join origin come from the Table TMLs. Without them the ERD still renders structure, and the run logs what was omitted.
• Layout positions auto-save in the browser's localStorage per model.
• The HTML file has no external dependencies — no CDN, no network requests.

Changelog