Skip to content

Import from other BI tools

Moving a dashboard into dbt Charts takes two steps:

  1. dct import fetches the dashboard from its tool into a source bundle: a local folder with the dashboard's layout, the SQL each tile runs, its current numbers, and the tool's own screenshot of it.
  2. An AI agent reads the bundle and writes a dbt Charts board with the same pages, tiles, controls, and numbers, then proves the numbers match.

The importer does the fetching; the agent does the translation. The import only writes the bundle folder; your boards are untouched until the agent writes the new one.

Why import

Looker, Omni, Sigma, and Hex are great partners to dbt, and plenty of teams will keep using them every day. These importers are not a push to leave them. They give you a copy of each dashboard in an open, plain-text standard that lives in git next to your dbt project, where it can do things a dashboard locked inside a BI tool cannot:

  • Get checked in CI. A model change that would break the dashboard fails the pull request, before anyone sees a broken chart.
  • Show up in lineage. You can see which dashboards depend on which models and columns, and catch a break before it ships.
  • Give AI agents real context. An agent can read exactly what each dashboard computes, its metrics, filters, and SQL, in a format it can parse, and answer questions or build new work on that knowledge.

Keep the dashboards your team already likes. The copy keeps their definitions portable, reviewable, and readable by every tool you add next.

Pick your tool

Tool Command Walkthrough
Looker dct import looker <dashboard URL> Looker
Omni dct import omni <dashboard URL> Omni
Sigma dct import sigma <workbook URL> Sigma
Hex dct import hex <project URL> Hex
Anything else Write a small fetcher, or use screenshots Other tools

Tableau, Metabase, Mode, Power BI, Superset, and the rest work too: the agent reads the bundle, not the tool, so any folder in the same layout migrates the same way. Other tools shows how to build one, and how to share your importer so the next person gets dct import <your tool> for free.

Before you start

  • dbt Charts installed in the project the board will live in (Installation), with a source that reaches the same warehouse tables the dashboard reads (Sources).
  • An API key for the tool. Each walkthrough says where to create one. dct import reads keys from environment variables only, and never writes them to disk.
  • An AI coding agent (Claude Code, Codex, Cursor, or similar) with the dbt Charts skills installed: run dct init skills once in the project.

Keep keys in a gitignored .env

Every importer reads its keys from the environment. The simplest setup is a .env file at the project root that git ignores:

git check-ignore .env || echo ".env" >> .gitignore

Add the variables your tool needs. Single quotes keep $ and spaces intact:

LOOKER_CLIENT_ID='...'
LOOKER_CLIENT_SECRET='...'

Then load the file in the same command as the import:

set -a; . ./.env; set +a; dct import looker https://acme.looker.com/dashboards/42

When a key is missing, dct import stops and names the variable and where to create it.

What's in a bundle

Every importer writes the same layout (Hex leaves kpi/ empty), to ./<tool>-<id>/ by default (--out picks another folder; --force replaces a non-empty one):

Path What it holds
outline.md Pages and tiles in reading order: type, title, position, fields, filters, formats, and which tiles each control reaches. Start here
raw definition The tool's own definition, byte for byte (dashboard.json, contents.json, or project.hex.yaml)
queries/ The SQL each tile runs, as the tool compiled it
kpi/ One CSV per single-number tile: the value the tile shows today
png/ The tool's own render of each page or chart
source.json Tool, URL, fetch time, and a checksum of the raw definition

A bundle is plain files. Read it, diff it, or commit it next to the board as a record of where the board came from. When the tool cannot produce one piece (a tile's SQL, a value, an image), the import usually still finishes and outline.md names the gap, on the tile's own line or under Not fetched. Each walkthrough lists the exceptions.

Migrate the bundle

Open your agent in the project and point it at the bundle:

Migrate ./looker-42 into a dbt Charts board.

The agent follows the board-migrate skill (dct skills board-migrate prints it). Expect it to:

  1. Ask one question: keep the tool's SQL verbatim, or rewrite each query cleanly over your dbt models. Verbatim is the faithful first step; clean is what you want to maintain.
  2. Build the structure first. Every page, tile, and control, in the source's order. Large dashboards (more than about ten queried tiles) pause here so you can confirm the structure before it wires real data.
  3. Wire the real queries against your warehouse.
  4. Prove parity. A table of every headline number in the source next to the board's number, so you can see they match before you retire the old dashboard.

The board keeps the source's data, names, and controls, and takes dbt Charts' own visual design: colors, fonts, number formats, and spacing come from your theme, not the old tool.

Next steps