Transformations (dbt)

Como criar data marts da camada semantic/ com dbt: métricas pré-calculadas, versionadas no Workspace Git e consultadas pelas Skills.

As Transformations são os data marts pré-agregados da camada semantic/ do Data Catalog. Você define cada uma em SQL via dbt, versiona no Workspace Git e as Skills consultam o resultado com performance de tabela pronta.

Elas são opcionais. O clean/ já serve Memory, Knowledge e as Skills. Você cria uma Transformation quando precisa de uma métrica calculada e recorrente que não vale recalcular a cada consulta.

---

As três camadas do Catalog

O Data Catalog organiza os dados em três camadas (Medallion). As Transformations produzem a última.

Camada	O que contém	Origem
raw/	Dados imutáveis, como chegaram da fonte	Ingestão dos Data Pipelines
clean/	Dados normalizados, deduplicados, com chaves padronizadas (CPF, CNPJ, email)	Transforms de conector
semantic/	Data marts pré-agregados, métricas calculadas	Transformations (dbt)

O clean/ é o tronco que alimenta Memory (grafos), Knowledge (vetores) e as Skills (SQL). O semantic/ é derivado dele, para quando a consulta precisa de uma métrica já calculada. Ver Data Catalog.

---

Pré-requisitos

Um conector ativo

É necessário pelo menos um conector sincronizado, porque a Transformation lê tabelas do clean/.

Acesso ao Workspace Git

Os modelos dbt são versionados no Workspace Git, com histórico e revisão por Pull Request.

---

Criar uma Transformation

O ponto de partida no Console é Data Catalog → Transformations.

1. Abrir Transformations no Console

   Acesse Data Catalog → Transformations para criar e gerenciar os data marts.

2. Escrever o modelo dbt

   Defina o data mart em SQL. O modelo materializa na camada semantic/, consumindo tabelas do clean/ como fonte.

   {{ config(materialized='table', schema='semantic') }}
   
   SELECT
     cliente_external_id,
     SUM(valor) AS receita_total
   FROM {{ ref('dim_clientes_clean') }}
   GROUP BY cliente_external_id
   
3. Versionar no Workspace Git

   Faça commit do modelo. A revisão por Pull Request dá o mesmo controle que você tem sobre código: histórico, rollback e aprovação antes de aplicar.

4. Consultar por uma Skill

   Depois de materializada, a tabela semantic/ fica disponível para uma Skill consultar via DuckDB, com métricas exatas.

Use schema='semantic' no config do modelo. Tabelas de conector materializam com schema='clean'; as Transformations é que produzem o semantic/.

---

Casos de uso típicos

Data mart	O que calcula
fct_health_score	Score de saúde por conta, a partir de uso, tickets e NPS
fct_receita_por_cliente	Receita agregada por cliente
fct_inadimplencia	Status de inadimplência por tomador
dim_clientes_clean	Clientes normalizados com chaves padronizadas

Exemplo — data mart para análise de churn (SaaS B2B)

O time de produto cria semantic/fct_health_score consolidando dados de uso do produto, tickets e NPS por conta. Uma Skill consulta esse mart via SQL para investigar quais contas estão com score degradado e cruzar com o histórico de interações da Memory.

---

Limitações conhecidas

• A Transformation depende de um conector ativo alimentando o clean/. Sem dado no clean/, não há fonte para o modelo.
• O semantic/ é derivado: mudanças no clean/ só aparecem no data mart no próximo run do dbt. [verificar]
• A frequência de recálculo do semantic/ acompanha o ciclo do pipeline. [verificar]

---

Próximos passos

Data Catalog

As três camadas, a linhagem e a governança de cada dataset.

Gerenciar a ontologia

As tabelas clean/ e semantic/ que alimentam os nós do grafo.

Configuração do Workspace

Onde os modelos dbt são versionados e revisados.

Monitoramento

Saúde dos datasets, frescor de dados e schemas quebrados.