> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/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](https://docs.strattum.ai/getting-started/configuration.md) 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](https://docs.strattum.ai/data-catalog/overview.md).

***

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

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

**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.

> [!NOTE]
>
> 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](https://docs.strattum.ai/data-catalog/overview.md)**
>
> As três camadas, a linhagem e a governança de cada dataset.

> **[Gerenciar a ontologia](https://docs.strattum.ai/admin/manage-ontology.md)**
>
> As tabelas clean/ e semantic/ que alimentam os nós do grafo.

> **[Configuração do Workspace](https://docs.strattum.ai/getting-started/configuration.md)**
>
> Onde os modelos dbt são versionados e revisados.

> **[Monitoramento](https://docs.strattum.ai/admin/monitoring.md)**
>
> Saúde dos datasets, frescor de dados e schemas quebrados.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.