Conversor TMDL para Databricks Metric Views
malcolndandaro/fabric-to-databricks-metric-views
Migra semântica Fabric/Power BI para Databricks Metric Views com verificação de parity
Ver no GitHubSkill que transforma modelos semânticos do Microsoft Fabric/Power BI (TMDL/TMSL) em Metric Views deployadas no Databricks Unity Catalog com verificação de paridade. Automatiza a migração da camada semântica (métricas, relacionamentos, dimensões) através de parsing determinístico, validação YAML e consulta única ao usuário para regras de negócio não-traduzíveis.
Instalação
npx convez-ai malcolndandaro/fabric-to-databricks-metric-views1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Migração de modelos semânticos do Power BI/Fabric para Databricks
- Conversão automática de medidas DAX em SQL metric views
- Validação e deploy de semantic layers em Unity Catalog
- Mapeamento inteligente de tabelas entre plataformas
Veredito

Skill especializado e bem-documentado para casos específicos de migração de plataforma. Exige pré-requisitos claros (dados já em UC, warehouse acessível, entendimento do modelo semântico) e um bom design de integração com agentes (questão única batched). Reduz drasticamente o overhead manual de tradução DAX-SQL, mas não é ferramenta geral — aplica-se estritamente a fluxos Fabric→Databricks.
README
A tradução para o português deste README ainda está na fila.
tmdl-to-ucmv
An agent skill that converts Microsoft Fabric / Power BI semantic model
exports (TMDL folders, zips, or TMSL model.bim) into deployed, verified
Databricks Unity Catalog Metric Views (CREATE VIEW ... WITH METRICS LANGUAGE YAML). Deterministic scripts parse the model, classify every DAX
measure, validate the generated YAML, and deploy + parity-check the result
against a SQL warehouse; the agent does the DAX-to-SQL judgment work guided
by bundled references, and consults you exactly once via a single batched
question card.
Important: this skill migrates the semantic layer (metrics, relationships, dimensions). It does not move data — your tables must already live in Unity Catalog before you start.
Before you start — checklist
Have these four things ready before invoking the skill:
1. Your semantic model export — any ONE of these shapes:
my-model/ ← PBIP "Save as project" or Fabric Git
└── <name>.SemanticModel/
└── definition/
├── model.tmdl
├── relationships.tmdl
├── expressions.tmdl (optional)
└── tables/
├── fact_sales.tmdl ← one file per table; measures + DAX live here
└── dim_*.tmdl
- …or a zip of that folder,
- …or a
model.bimfile (older TMSL JSON export), - …or the raw JSON response of Fabric REST
POST /v1/workspaces/{ws}/semanticModels/{id}/getDefinition?format=TMDL.
How to get the export (full recipes with code in
references/tmdl-primer.md § How customers export TMDL):
| If your model is… | Export with |
|---|---|
| Editable in Power BI Desktop | File → Save as → Power BI project (.pbip) (enable the TMDL preview option) |
| In Fabric, Git integration on | Commit the workspace — the .SemanticModel/definition/ folder lands in your repo |
| In Fabric, no Git | A Fabric notebook with sempy / the REST getDefinition API (copy-paste recipe in the primer) |
Fabric-edited models cannot be downloaded as
.pbit— the file comes out empty. That's a Microsoft limitation, and exactly why this skill reads TMDL instead.
2. Your data already in Unity Catalog — a catalog.schema containing
the tables your model's queries point at (the fact and dimension tables).
Know that target catalog.schema name; the skill will map the model's
tables to it automatically and show you the mapping for review. If table
names differ significantly from the Power BI names, you can pre-pin
mappings in an overrides.yaml (template: assets/overrides.example.yaml)
— otherwise just let the skill derive them.
3. Databricks access
- A SQL warehouse (serverless is fine) the skill can use to probe,
deploy, and verify. DBR/warehouse gates: 17.3+ to create metric views,
18.1+ for window
offset, one-to-many and nested joins. - Running locally (Claude Code): an authenticated Databricks CLI
(
databricks auth login) and the profile name. - Running in Genie Code: nothing extra — the workspace session itself executes the SQL.
4. Ten minutes of a person who knows the metrics. The skill is autonomous, but untranslatable business rules (e.g. ALLSELECTED measures, calculation groups) come back as ONE numbered question card with a recommended answer per question. Someone should be able to answer it — or accept the recommendations.
Invoking the skill
Tell the agent three things: where the export is, the target
catalog.schema, and (locally) the CLI profile. Example prompt:
Convert the semantic model export at
./exports/sales-model/into metric views inmain.gold_semantics. Databricks profilemy-profile, warehouse<id>(optional — it auto-picks otherwise).
What happens next:
- The skill parses the export, maps tables to UC, classifies all measures, and translates everything it can — no interaction needed.
- You get one question card (derived table mappings to skim + numbered
questions, each with a recommended answer). Answer it once; answers are
stored in
overrides.yamlso re-runs never re-ask. - The skill validates every generated YAML, deploys the views, runs smoke + parity queries against your source tables, and writes the report.
- All artifacts persist in a work dir (
tmdl_to_ucmv_work/<model>/):inventory.json,plan.json,mv_*.sql,overrides.yaml,verify_*.json,report.md.
What it produces
- One metric view per fact table (
mv_<domain>.sqlDDL files), validated before anyone sees them and deployed via the Statement Execution API. - A per-measure migration report (
report.md): status (TRANSLATED/NEEDS_REVIEW/DISPLAY_ONLY/OUT_OF_SCOPE), confidence, the original DAX, applied transformations, assumptions, and the decisions log. - Parity results (
verify_*.json): metric-view numbers checked against direct SQL on the source tables. - A re-runnable
overrides.yamlcapturing every human decision, so re-runs never re-ask an answered question.
What it does NOT do
- No data migration — tables must already be in Unity Catalog.
- No live Fabric extraction — the skill documents the export recipes
(PBIP save, Fabric Git, REST
getDefinition) and accepts their outputs, but never authenticates to Fabric itself. - No report/visual migration — semantic model only; dashboards are out of scope.
- No connection repointing — that is the PBI-on-Databricks migration accelerator's territory.
- No RLS implementation — UC row filters are recommended and reported, not auto-created.
- No
.pbixbinary parsing, no materialization tuning, no Genie space auto-creation (guidance only), no calculation-group auto-expansion (flagged for human curation).
Install
Claude Code (local)
Copy (or symlink) the skill folder into your personal skills directory:
cp -R /path/to/tmdl-to-ucmv ~/.claude/skills/tmdl-to-ucmv
Genie Code (Databricks workspace)
One command, parameterized by CLI profile (email is derived from the
profile's identity; pass --user-email to override):
./deploy/deploy.sh --profile <PROFILE>
This stages SKILL.md + scripts/ + references/ + assets/ to
/Workspace/Users/<email>/.assistant/skills/tmdl-to-ucmv/ and verifies the
remote file listing. For an all-users install, run
./deploy/deploy.sh --profile <P> --target workspace to print the shared-path
guidance.
databricks-agent-skills / aitools compatibility
The folder follows the databricks-agent-skills packaging shape — a skill
directory with SKILL.md (frontmatter: name, description,
compatibility, metadata.version) plus scripts/, references/, and
assets/ — so it is layout-compatible with databricks aitools install-style
distribution (which auto-detects Claude Code's ~/.claude/skills/, Cursor,
Codex, and Copilot directories). It is a field asset, not part of that
repo's catalog; install via the two paths above.
Requirements
- Python 3.10+ with PyYAML.
- Databricks CLI authenticated (
databricks auth login) for catalog probing, deploy, and verify when running locally (Genie Code runs SQL in-session instead). - Warehouse/runtime gates: DBR 17.3+ to create metric views; 18.1+ for
window-measure
offset, one-to-many joins, and nested joins.
After the migration
- Review
report.md— especially the Assumptions log and anything notTRANSLATED. - Certify the views Genie should prefer:
SET TAG ON TABLE <view>system.certification_status=certified``. - Add the views to your Genie space; the carried-over
display_name,synonyms, andformatmetadata is what Genie consumes. - If YTD/period numbers look wrong at some grain, read the window grain
rule in
references/time-intelligence.mdbefore changing anything.
Disclaimer
Generated by the tmdl-to-ucmv field skill — an unsupported tool, not a Databricks product. Review this report and the parity results before relying on the migrated numbers.
Every migration report carries this disclaimer verbatim. The skill is a kickstart tool: it gets a semantic model migrated, measured, and parity-checked, but the customer owns the result and its iteration — naming, business-rule refinement, RLS, and ongoing metric governance. Engage your Databricks account team or a partner for productionization.