Skip to content

Import from Omni

Omni is a great partner to dbt, and this importer is not meant to replace it. It keeps a copy of your Omni work in dbt Charts' open format, in git next to your dbt project, so CI can catch model changes that would break it, lineage covers it, and AI agents can read exactly what it computes. See Why import.

This walkthrough moves one Omni dashboard into a dbt Charts board. Read Import from other BI tools first for the overall flow.

1. Create an Omni API key

  1. In Omni, open Settings → API Keys. Creating keys needs an Omni admin.
  2. Create a key and copy it.

Put it, and your Omni address, in your gitignored .env:

OMNI_API_KEY='...'
OMNI_BASE_URL='https://acme.omniapp.co'

OMNI_BASE_URL is only required for --list and for bare ids. A full dashboard URL carries its own origin.

2. Find the dashboard

Copy the URL from your browser, or list what the key can see:

set -a; . ./.env; set +a; dct import omni --list

Each line shows the dashboard's identifier, its scope, its name, and its URL.

3. Import the dashboard

set -a; . ./.env; set +a; dct import omni https://acme.omniapp.co/dashboards/abc12345

or, with OMNI_BASE_URL set:

dct import omni abc12345

The command writes ./omni-abc12345/. Use --out for another folder and --force to refresh an existing bundle.

What you get

Path From Omni
dashboard.json Omni's dashboard export: pages, tile layout, and dashboard filters
outline.md Pages and tiles in layout order, with fields, filters, and options
queries/ Each tile's saved query definition and the SQL Omni plans for it
kpi/ The current value of each single-number tile
png/ Omni's render of each dashboard page
source.json The fetch record

Some Omni tiles run in two steps: a warehouse query, then a DuckDB query over its result. Those get two files, queries/<tile>.sql (the warehouse step, runnable as is) and queries/<tile>.post.sql (the second step). The agent folds both into one query for the board.

A tile Omni cannot plan, or a KPI whose value run fails, is noted on that tile's line in outline.md; a page render that fails or does not finish is listed under Not fetched. The rest of the bundle is written.

4. Migrate it

Migrate ./omni-abc12345 into a dbt Charts board.

See Migrate the bundle for what the agent does.

Omni-specific notes

  • SQL and values are at the dashboard's filter defaults. The importer applies each dashboard filter's default before planning a tile and before recording its KPI value. The filters are listed in the outline and become board controls; check parity with the controls at those same defaults.
  • Omni topics and the semantic model are not copied. The bundle carries the SQL Omni generated. In clean mode the agent rewrites it over your dbt models.
  • The export endpoint is in beta at Omni. If Omni changes its shape, the import fails loudly rather than writing a partial bundle. Report it (see Other tools) and use screenshots in the meantime.

Troubleshooting

Message Fix
OMNI_API_KEY is not set Load your .env in the same command
pass either a dashboard or --list, not both or neither Give a URL or id, or --list, but not both
HTTP 429 (rate limit) Wait a minute and rerun with --force
A page under Not fetched with Omni render already in progress Another render of that dashboard was running; rerun with --force later