> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/getting-started/configuration) 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](/data-catalog/overview).

***

## Pré-requisitos

<CardGroup cols={2}>
  <Card title="Um conector ativo" icon="plug">
    É necessário pelo menos um conector sincronizado, porque a Transformation lê tabelas do `clean/`.
  </Card>

  <Card title="Acesso ao Workspace Git" icon="code-branch">
    Os modelos dbt são versionados no Workspace Git, com histórico e revisão por Pull Request.
  </Card>
</CardGroup>

***

## Criar uma Transformation

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

<Steps>
  <Step title="Abrir Transformations no Console">
    Acesse **Data Catalog → Transformations** para criar e gerenciar os data marts.&#x20;
  </Step>

  <Step title="Escrever o modelo dbt">
    Defina o data mart em SQL. O modelo materializa na camada `semantic/`, consumindo tabelas do `clean/` como fonte.

    ```sql theme={null}
    {{ config(materialized='table', schema='semantic') }}

    SELECT
      cliente_external_id,
      SUM(valor) AS receita_total
    FROM {{ ref('dim_clientes_clean') }}
    GROUP BY cliente_external_id
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Consultar por uma Skill">
    Depois de materializada, a tabela `semantic/` fica disponível para uma Skill consultar via DuckDB, com métricas exatas.
  </Step>
</Steps>

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

***

## 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            |

<Accordion title="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.
</Accordion>

***

## 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

<CardGroup cols={2}>
  <Card title="Data Catalog" icon="folder-open" href="/data-catalog/overview">
    As três camadas, a linhagem e a governança de cada dataset.
  </Card>

  <Card title="Gerenciar a ontologia" icon="diagram-project" href="/admin/manage-ontology">
    As tabelas clean/ e semantic/ que alimentam os nós do grafo.
  </Card>

  <Card title="Configuração do Workspace" icon="folder-gear" href="/getting-started/configuration">
    Onde os modelos dbt são versionados e revisados.
  </Card>

  <Card title="Monitoramento" icon="gauge-high" href="/admin/monitoring">
    Saúde dos datasets, frescor de dados e schemas quebrados.
  </Card>
</CardGroup>