Use this guide when you're replacing an existing BI tool with Qyra. 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 Qyra 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 Qyra skills, and finish by rebuilding the dashboards visually in Qyra.

1. Install the Qyra 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 Qyra YAML, metrics, and dashboards correctly.

qyra install-skills

2. Set up your migration workspace

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

3. Extract your source information

Pull every piece of information out of the source BI tool that Qyra 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.

5. Translate the modeling into Qyra

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

/developing-in-qyra

Read the LookML files under migration/source/looker/ and profile the
corresponding tables in our warehouse. For each Looker view that
underlies a dashboard in migration/source/screenshots/, propose a
Qyra model with matching dimensions and metrics. Do not create
files yet — list the models and metrics you plan to create.

qyra lint

qyra deploy

6. Rebuild the dashboards

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

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

Once the content works, take a pass to align it with Qyra conventions and any modeling standards the team already follows.

• Follow Qyra's modeling guidance. Read modeling strategies 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. Qyra'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 Qyra user attributes.

Next steps

• Install agent skills
• Qyra YAML
• Modeling strategies
• Content as code