Skip to main content
Use this guide when you’re replacing an existing BI tool with Lightdash. It works for any source tool — Looker, Tableau, Power BI, Metabase, Mode, Sigma, or an in-house solution — because the process is the same: extract what you have, translate the modeling into Lightdash YAML or dbt, and rebuild the dashboards on top of your new semantic layer. The steps below are designed to be followed in order. You’ll do most of the modeling work with an AI coding agent (Claude Code, Cursor, or Codex) using Lightdash skills, and finish by rebuilding the dashboards visually in Lightdash.
Before you start, make sure you have:
  • A Lightdash project connected to your warehouse. See Setting up a new project.
  • Admin (or export-equivalent) access to the BI tool you’re migrating from.
  • A dbt project (or an empty repo where one will live) connected to the same warehouse.

​
1. Install the Lightdash CLI and skills

The AI-assisted path is by far the fastest way to migrate. Install the CLI and skills first so your coding agent knows how to write Lightdash YAML, metrics, and dashboards correctly.
1

Install the Lightdash CLI

Follow the CLI installation guide and authenticate against your Lightdash project.
2

Install Lightdash skills

Run this from your dbt or YAML project root:
This installs skills into .claude/skills/ (also read by GitHub Copilot). For Cursor or Codex, pass --agent cursor or --agent codex. To share across projects, add --global. See Agent skills for all options.
3

Confirm your agent picks up the skills

In Claude Code, prefix migration prompts with /developing-in-lightdash so the agent uses the Lightdash context. Cursor and Codex pick the skills up automatically.

​
2. Set up your migration workspace

Before touching your source BI tool, get a clean workspace ready to receive the migrated content.
1

Create a migration branch in your dbt or YAML repo

Work on a branch (for example migration/from-looker) so you can iterate without affecting production models.
2

Create a Lightdash preview project

Use a preview project or a separate development project so the migrated content is isolated until you’re ready to promote it. This gives you a safe place to validate metrics against the source tool.
3

Create a working folder for source exports

In the repo, add a folder like migration/source/ to hold everything you export from the source tool (LookML, .twb files, .pbix unpacks, question JSON, screenshots). Your agent will read from this folder.

​
3. Extract your source information

Pull every piece of information out of the source BI tool that Lightdash will need to rebuild the reports. What you extract depends on the tool, but the goal is the same: capture the modeling logic, the queries, and the visual layout. Choose the option that matches your source tool. If more than one applies, do them all — the more source material your agent has, the better the translation.

​
Modeling logic as code

If the source tool stores modeling logic in files, export those files first. This is the highest-signal input for the migration.
  • Looker — clone the LookML project (.lkml, .view.lkml, .model.lkml, .dashboard.lookml).
  • dbt-based tools (Metabase Metrics Layer, Mode with dbt) — you already have the source; note which models are actually used by the reports.
  • Sigma / Hex / Omni — export workbook or dataset definitions as JSON or YAML where the tool supports it.
Copy the files into migration/source/ in your repo.

​
Workbooks and reports as files

If the source tool stores reports as binary or archive files, unpack them so the agent can read the SQL and field definitions.
  • Tableau — save workbooks as .twbx (packaged) then unzip to expose the underlying .twb XML. The XML contains data source definitions, calculated fields, filters, and worksheet layouts.
  • Power BI — export .pbix files and unpack them (for example with a .pbix viewer or pbi-tools) to extract the data model, DAX measures, and report layout as JSON/XML.
  • Mode / Metabase / Redash — export questions or reports as SQL. Group them by dashboard so you know which queries feed which report.
Put the extracted files under migration/source/<tool>/.

​
API extraction

For SaaS BI tools without a file export, pull the definitions through the API. This is usually the best route when there are hundreds of reports and manual export isn’t practical.
  • Looker — Looker API endpoints for looks, dashboards, and queries.
  • Tableau — Metadata API for workbooks, data sources, calculated fields, and lineage.
  • Power BI — REST API for datasets, reports, and DAX definitions.
  • Metabase — /api/card and /api/dashboard for questions and dashboards.
  • Mode — /api/{workspace}/reports for reports and their queries.
Write a small script to dump the responses to JSON in migration/source/api/. Include the raw SQL, field definitions, filters, and any joins.

​
Direct SQL

For everything else — bespoke reports, undocumented queries, ad-hoc dashboards — capture the executed SQL. Query your warehouse’s query history (Snowflake QUERY_HISTORY, BigQuery INFORMATION_SCHEMA.JOBS, Redshift STL_QUERY) filtered to the BI tool’s service user to see what actually runs in production. Save the top queries by frequency into migration/source/sql/.

​
4. Take screenshots of the source dashboards

Screenshots are the reference for rebuilding the visual layer. Your coding agent can’t see the source tool, so it needs the images to match layout, chart types, and filter positions.
1

Capture each dashboard end to end

Take a full-page screenshot of every dashboard you’re migrating. Include the filters, tab structure, and any drilldowns.
2

Capture chart-level detail where it matters

For complex visualizations (custom colors, conditional formatting, mixed chart types), take a zoomed-in screenshot too. Also grab the underlying query where the source tool exposes it.
3

Store screenshots alongside the source files

Save them under migration/source/screenshots/, named by dashboard. Reference them in your prompts so the agent uses them when rebuilding layouts.

​
5. Translate the modeling into Lightdash

With everything extracted, use your coding agent to translate the source modeling into Lightdash’s semantic layer. Do this in passes — models first, then metrics, then joins — rather than all at once.
1

Prompt the agent to profile the warehouse and read the source

Point the agent at both the source files and your warehouse schema. For example:
Review the plan before letting it write files.
2

Generate models one source at a time

Ask the agent to write the Lightdash YAML (or dbt meta tags) for one source at a time. See Lightdash YAML for the format. After each file, run:
Fix errors before moving on.
3

Translate metrics, calculated fields, and measures

Map source metric types to Lightdash metric types. Common mappings:Ask the agent to add descriptions and categories so the migrated fields land in the metrics catalog cleanly.
4

Rebuild joins

Translate source joins to Lightdash joins. Specify the relationship (one-to-many, many-to-one, one-to-one) — this is what unlocks correct fan-out handling.
5

Deploy to your preview project

Then run lightdash validate to catch broken references.

​
6. Rebuild the dashboards

With the semantic layer in place, rebuild the dashboards on top of it.
1

Rebuild charts against the migrated tables

Open each source dashboard screenshot side by side with Lightdash. For each chart, build the equivalent in Lightdash using the migrated metrics and dimensions. See Configuring your charts and the chart types reference.If you’d rather do this conversationally, ask your agent to build the dashboards for you — it can generate dashboards as code from the screenshots and the migrated models.
2

Rebuild dashboard-level filters and tabs

Recreate the source dashboard’s filter set with dashboard filters and multi-tab layouts. Match the visual grouping from the screenshots.
3

Validate the numbers match the source

For every migrated dashboard, run the same query in the source tool and in Lightdash and compare the results. Any mismatch usually points to:
  • A missing or mismapped join
  • A different aggregation type
  • A silent filter in the source tool (default date range, hidden user filter)
  • A timezone difference — see Working with timezones
Do this before you cut anyone over.

​
7. Layer in best practices and the customer’s own conventions

Once the content works, take a pass to align it with Lightdash conventions and any modeling standards the team already follows.
  • Follow Lightdash’s modeling guidance. Read dbt model best practices for Lightdash and apply it: name fields consistently, keep grain explicit, use pre-aggregates where warranted.
  • Apply the customer’s own style guide. If the team has a metric naming convention, category structure, or documentation standard, feed that into the agent as extra context so the migrated fields match. Skills read anything in the project — a MODELING_GUIDE.md at the repo root is often enough.
  • Write good descriptions. See Writing descriptions. Migrations are the best time to fix the descriptions that never got written in the source tool.
  • Verify canonical content. Mark the migrated dashboards and charts as verified content so users know which reports are the source of truth going forward.
  • Set up promotion. Once validated in preview, use content promotion to move dashboards to production.
  • Plan the cutover. Announce a date, keep the source tool read-only for a defined grace period, and use scheduled deliveries to replace any recurring exports from the old tool.

​
Common pitfalls

  • Migrating everything. Most BI tools carry hundreds of stale reports. Use warehouse query history to see what’s actually used, and migrate that subset first.
  • Trying to match the old tool 1:1. Lightdash’s metric definitions are reusable across charts. Consolidate duplicates instead of copying every one-off calculated field.
  • Skipping joins. LookML explores and Tableau data sources bake in joins that aren’t obvious from the SQL. Read the model definitions, not just the queries.
  • Forgetting user attributes and access. Row-level filters and user attributes from the source tool need to be re-modeled with Lightdash user attributes.

​
Next steps