convez.ai
SkillDados & AnalyticsAvançado
malcolndandaro

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 GitHub
InicialPluginScore · de 0 a 100

Skill 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-views

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.bim file (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 DesktopFile → Save as → Power BI project (.pbip) (enable the TMDL preview option)
In Fabric, Git integration onCommit the workspace — the .SemanticModel/definition/ folder lands in your repo
In Fabric, no GitA 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 in main.gold_semantics. Databricks profile my-profile, warehouse <id> (optional — it auto-picks otherwise).

What happens next:

  1. The skill parses the export, maps tables to UC, classifies all measures, and translates everything it can — no interaction needed.
  2. 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.yaml so re-runs never re-ask.
  3. The skill validates every generated YAML, deploys the views, runs smoke + parity queries against your source tables, and writes the report.
  4. 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>.sql DDL 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.yaml capturing 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 .pbix binary 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 not TRANSLATED.
  • 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, and format metadata is what Genie consumes.
  • If YTD/period numbers look wrong at some grain, read the window grain rule in references/time-intelligence.md before 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.

Ver o original no GitHub

Bom para

Relacionados