Data contracts com dbt: como impedir dashboards quebrados com testes e SLAs
Você publica um dashboard, a reunião executiva depende dele e, no dia seguinte, métricas somem ou aparecem vazias. O problema quase sempre não é o gráfico e sim a ausência de um contrato explícito entre fonte, transformação e consumo.
Neste guia você aprende a transformar o data build tool em guardrail de qualidade usando data contracts simples, testes automatizados, documentação que o negócio entende e SLAs de atualização conectados ao orquestrador.
O objetivo é detectar mudanças incompatíveis cedo, comunicar expectativas entre times de origem e de consumo e proteger decisões com dados confiáveis.
Para referência em governança e qualidade de dados no contexto brasileiro, considere o Guia de Governança de Dados do Governo Federal e a Cartilha de Governança de Dados. Se você quer aprender com casos práticos e exercícios orientados, veja o nosso Bootcamp de Data Analytics.
O que é um data contract na prática
Um data contract é um acordo verificável sobre a estrutura, a qualidade, a semântica e a disponibilidade de um conjunto de dados.
Em outras palavras, ele define o que pode ser esperado de uma tabela, modelo ou fonte antes que esses dados sejam usados por dashboards, análises, produtos ou modelos de IA.
No dbt, esse contrato pode aparecer em diferentes partes do projeto: na configuração dos modelos, na documentação, na separação de camadas e, principalmente, nos testes que rodam a cada execução.
Na prática, um bom contrato responde perguntas como:
- quais colunas devem existir?
- quais campos são obrigatórios?
- quais valores são aceitos?
- qual é a chave única?
- quais relacionamentos precisam ser preservados?
- com que frequência os dados devem ser atualizados?
- quem deve ser avisado quando algo falhar?
Dessa forma, o contrato deixa de ser uma combinação informal entre times e passa a ser um mecanismo operacional de confiança.
Para uma base conceitual em língua portuguesa sobre qualidade de dados, vale consultar a revisão integrativa publicada na SciELO: SciELO — Qualidade de dados na Web
Arquitetura mínima no dbt para contratos estáveis
Para que os data contracts com dbt funcionem bem, a arquitetura precisa ser simples, clara e fácil de manter. Um bom ponto de partida é organizar o projeto em duas camadas principais: staging e core.
Na camada de staging, você aproxima o modelo da fonte original, padroniza nomes, ajusta tipos de dados e aplica validações básicas. Nesse momento, entram testes como campos obrigatórios, unicidade de chaves e formatos esperados.
Já na camada core, ficam as regras de negócio. É nela que você consolida dimensões e fatos, valida relacionamentos entre tabelas e prepara os modelos que serão consumidos por dashboards, análises e produtos de dados.
Essa separação evita que regras importantes fiquem espalhadas pelo projeto. Além disso, facilita a manutenção quando uma fonte muda, uma métrica é ajustada ou um consumidor passa a depender de uma nova tabela.
Por isso, a documentação do projeto também deve ser publicada e mantida atualizada. Assim, o consumidor entende o que pode esperar de cada modelo, enquanto o time de engenharia consegue avaliar impacto antes de alterar estruturas críticas.
Para contextualizar orquestração e DAGs em português, a entrada de Engenharia de Dados na Wikipédia oferece uma visão geral do papel de orquestradores como o Apache Airflow.
Testes no dbt que param quebras antes do consumidor ver
Os testes são a fiscalização do contrato. Sem eles, o contrato vira apenas documentação. Com eles, o pipeline passa a validar automaticamente se os dados continuam respeitando as regras combinadas.
No dbt, você pode começar com testes básicos, como:
- campos não nulos;
- unicidade de chaves;
- domínio de valores aceitos;
- relacionamentos entre fatos e dimensões;
- validação de tipos e formatos;
- regras de negócio específicas.
Além disso, é importante diferenciar falhas críticas de alertas menos urgentes. Uma dimensão ausente em uma tabela de fatos, por exemplo, pode comprometer um dashboard inteiro. Por outro lado, uma variação pequena em um campo auxiliar pode exigir investigação, mas não necessariamente bloquear a publicação.
Nesse contexto, padronizar severidade, mensagens e responsáveis faz diferença. Quando um teste falha, o time precisa entender rapidamente o que aconteceu, qual modelo foi afetado e qual consumidor pode sofrer impacto.
Como resultado, mudanças incompatíveis deixam de chegar silenciosamente ao dashboard e passam a ser tratadas antes da reunião executiva.
Se você quer aprofundar e se embasar critérios de qualidade, a literatura em português da SciELO ajuda a transformar princípios em métricas observáveis.
Documentação e lineage que ajudam negócio e engenharia
Um contrato só é útil quando as pessoas conseguem entendê-lo. Por isso, além dos testes, é essencial documentar modelos e colunas com linguagem de negócio. Não basta dizer que uma coluna se chama customer_id; é preciso explicar o que ela representa, quando é preenchida, qual sistema a origina e como deve ser usada.
Na prática, uma boa documentação deve indicar:
- descrição do modelo;
- significado das colunas;
- responsável técnico;
- responsável de negócio;
- criticidade do dado;
- dashboards ou produtos consumidores;
- frequência de atualização;
- regras de qualidade aplicadas.
Além disso, o lineage ajuda a visualizar dependências entre fontes, transformações e consumidores. Dessa forma, antes de alterar uma tabela, o time consegue entender quais dashboards, relatórios ou produtos a mudança pode impactar.
Esse cuidado reduz retrabalho e melhora a conversa entre engenharia, analytics, produto e áreas de negócio.
Em governança, a página de Governança de Dados do Gov.br traz papéis, responsabilidades e recomendações que podem ser adaptadas ao catálogo e ao processo de documentação do seu time.
Se você quiser ver boas práticas aplicadas e estudos do nosso ecossistema, navegue pelo Blog da Tekne.
SLAs de atualização conectados ao orquestrador
Além de qualidade, um data contract também deve definir quando os dados precisam estar disponíveis.
Afinal, um dado correto, mas atrasado, pode ser inútil para uma decisão operacional. Por isso, os SLAs de atualização precisam fazer parte do contrato.
Na prática, o SLA define a janela esperada para atualização de uma tabela, modelo ou dashboard. Por exemplo: uma base de vendas pode precisar estar atualizada todos os dias até 8h, enquanto uma base financeira pode ter uma janela diferente.
Quando esses SLAs são conectados ao orquestrador, o time consegue monitorar atrasos e acionar alertas automaticamente. Em ambientes com Apache Airflow, por exemplo, tarefas, políticas de reexecução e notificações ajudam a tornar a entrega de dados mais previsível.
Para uma introdução ao conceito de SLA, veja:
Nesse contexto, algumas políticas úteis incluem:
- marcar o job como falho quando a janela de frescor estourar;
- interromper a publicação quando um teste crítico falhar;
- notificar responsáveis com mensagem clara;
- registrar incidentes para análise posterior;
- definir política de reexecução quando a falha for temporária.
Dessa forma, o contrato não controla apenas a estrutura dos dados, mas também sua disponibilidade para o negócio.
Como detectar e comunicar breaking changes cedo
Mudanças incompatíveis, também chamadas de breaking changes, são alterações que podem quebrar consumidores existentes.
Isso pode acontecer quando uma coluna é removida, um tipo de dado muda, uma regra de negócio é alterada ou uma tabela deixa de ser atualizada dentro da janela esperada.
Antes do merge, é recomendável realizar revisão obrigatória, rodar build e testes em ambiente de homologação e verificar se alterações estruturais foram documentadas para quem consome os dados.
Depois do merge, o pipeline deve executar transformações e testes em produção. Se uma falha crítica acontecer, o pipeline precisa bloquear a publicação, e o time deve abrir o incidente com clareza.
Para organizar esse processo, mantenha um changelog voltado ao negócio. Ele pode classificar mudanças por impacto:
- estrutural;
- semântico;
- operacional;
- relacionado a SLA;
- relacionado a consumidores críticos.
Além disso, avise sobre janelas de migração com antecedência. Assim, os times de negócio não descobrem a mudança apenas quando o dashboard para de funcionar.
Para referência sobre merge no Git, consulte: Git Book — Branches, ramificação e merge
Em times que já integram IA generativa ao fluxo de dados, os riscos podem aumentar. Nesse caso, vale consultar o OWASP Top 10 para aplicações com LLM: OWASP Top 10 para Aplicações com LLM
Exemplo conceitual de contrato de tabela
Sem entrar em código, o contrato de uma tabela de fatos deve responder quatro perguntas essenciais:
- qual é o identificador único?
- quais colunas são obrigatórias?
- qual é o domínio de valores aceitos?
- quais dimensões precisam existir previamente?
Além dessas questões, o contrato também deve indicar quem é o responsável, qual é a janela de atualização e como as falhas devem ser tratadas.
Por exemplo, uma tabela de pedidos pode exigir que order_id seja único, que customer_id nunca esteja vazio, que o status do pedido pertença a uma lista fechada de valores e que todo cliente exista previamente na dimensão de clientes.
Quando o time documenta e testa esses elementos, o pipeline detecta mudanças incompatíveis antes que elas cheguem ao usuário.
Como resultado, o time reduz a chance de dashboards quebrados, métricas vazias e decisões baseadas em dados incompletos.
Checklist de implantação para data contracts com dbt
Use este checklist para transformar o conceito em prática:
- separar staging de core e remover regras de negócio da camada de staging;
- declarar fontes com janelas de atualização e critérios de qualidade;
- incluir testes de integridade e relacionamento entre fatos e dimensões;
- padronizar testes de negócio e severidade de falhas;
- publicar documentação com descrições claras, responsáveis e criticidade;
- declarar consumidores críticos, como dashboards executivos e produtos de dados;
- configurar SLAs no orquestrador com alertas e política de reexecução;
- manter changelog e versionamento para mudanças incompatíveis.
Esse checklist não precisa nascer perfeito. O mais importante é começar pelos conjuntos de dados mais críticos e evoluir o contrato conforme o time aprende.
Plano em 7 dias para sair do papel
Para começar sem travar em excesso de planejamento, siga um roteiro simples de implantação.
No primeiro dia, mapeie as fontes críticas e identifique quais consumidores dependem delas. Inclua dashboards, relatórios, produtos internos e rotinas operacionais.
No segundo dia, organize as camadas staging e core, deixando claro onde ficam padronizações técnicas e onde entram regras de negócio.
Em seguida, declare fontes, janelas de atualização e testes básicos, como não nulo, unicidade e domínio de valores.
No quarto dia, inclua testes de relacionamento entre fatos e dimensões. Além disso, adicione pelo menos um teste de negócio que represente uma regra importante para a operação.
Depois disso, complete descrições, responsáveis, criticidade e consumidores. Publique a documentação para que engenharia e negócio consultem a mesma referência.
No sexto dia, ative SLAs no orquestrador e configure alertas para atrasos, falhas críticas e violações de qualidade.
Por fim, simule uma mudança que quebre o contrato e valide se o pipeline bloqueia a publicação. Essa etapa é importante porque testa não apenas a configuração, mas também o processo de resposta do time.
Conclusão
Quer dar o próximo passo com orientação prática, casos reais e revisão de arquitetura
Inscreva-se no Bootcamp de Data Analytics e BI e traga seu projeto para a bancada. Você sai com contratos definidos, testes padronizados e SLAs operando no seu orquestrador.
Prefere explorar ideias aplicáveis agora
Acesse o Blog da Tekne e salve dois conteúdos de referência para discutir com o time em uma reunião de 30 minutos. Transforme o que fizer sentido em padrão operacional do seu pipeline.
Como agir hoje
Escolha um conjunto de dados crítico e escreva o contrato mínimo com dono, chaves obrigatórias, domínio de valores e janela de atualização. Converta duas regras de negócio em testes automatizados. Defina o canal de alerta e a política de bloqueio quando um teste falhar. Marque uma revisão semanal para manter o contrato vivo.
