Há uma classe de falhas de dados que nunca dispara um alarme. O pipeline corre até ao fim, o relatório atualiza à hora do costume, os números aparecem no dashboard — e estão errados. Na origem, alguém numa equipa a montante mudou o nome de uma coluna, trocou o formato de uma data ou passou a enviar valores em cêntimos em vez de euros. Ninguém avisou, porque ninguém sabia que aquele campo tinha consumidores do outro lado.
Este é o problema silencioso da engenharia de dados moderna. Os dados atravessam dezenas de sistemas e equipas, mas os acordos sobre o que cada campo significa vivem, na melhor das hipóteses, na cabeça de quem construiu o pipeline. Quando essa pessoa muda de projeto, ou quando o volume cresce, o custo aparece — em relatórios refeitos, decisões adiadas e confiança perdida na equipa de dados.
Um contrato de dados é a resposta a este problema. É um acordo explícito, versionado e verificável entre quem produz os dados e quem os consome, que descreve a estrutura, o significado e as garantias de qualidade daquilo que é partilhado. Este artigo explica o que é, o que deve conter e como o introduzir sem transformar tudo numa burocracia que ninguém cumpre.
O que é um contrato de dados
Um contrato de dados formaliza uma promessa. A equipa que produz um conjunto de dados compromete-se a entregá-lo com uma determinada forma e qualidade, e a avisar antes de mudar essa promessa. Não é um documento esquecido numa wiki: é uma especificação legível por máquinas, guardada junto ao código e verificada automaticamente sempre que os dados mudam.
A melhor analogia é a de uma API. Quando uma equipa expõe uma API, publica um contrato — os campos, os tipos, o que é obrigatório — e os consumidores constroem em cima dessa promessa a confiar que ela não muda de um dia para o outro. Durante anos, os dados analíticos não tiveram esta disciplina: uma tabela num data warehouse era tratada como um detalhe interno que qualquer pessoa podia alterar. O contrato de dados traz para o mundo analítico o mesmo rigor que a engenharia de software há muito aplica às suas interfaces.
O problema: dados que partem em silêncio
Para perceber o valor de um contrato, é preciso olhar para como as coisas partem sem ele. A falha mais comum é a mudança de schema a montante: uma coluna que desaparece, muda de tipo ou passa a admitir valores nulos. O pipeline pode não falhar de imediato — muitas vezes continua a correr e a escrever dados, só que errados.
Depois há as mudanças de significado, ainda mais traiçoeiras porque o schema nem sequer muda. O campo estado_encomenda passa a incluir um novo valor que nenhum relatório previa. A moeda de valor_total muda de euros para dólares numa região. A definição de cliente ativo é alterada na origem sem que a equipa de analytics saiba. O tipo continua correto; o número deixa de significar o que significava.
O denominador comum é a ausência de um acordo explícito. Quem produz os dados não sabe quem os consome, nem com que expectativas. Quem os consome não tem forma de saber que a promessa mudou. Um contrato torna esse acordo visível e, sobretudo, verificável.
O que inclui um bom contrato de dados
Um contrato útil vai muito além da lista de colunas. Deve descrever, de forma legível por máquinas e por pessoas, os seguintes elementos:
- Schema e tipos. Os campos, os seus tipos, quais são obrigatórios e quais admitem nulos. É a base, mas é apenas o começo.
- Semântica. O que cada campo significa em linguagem de negócio: unidades, moeda, fuso horário, granularidade de cada linha e valores permitidos em campos categóricos.
- Garantias de qualidade. Regras que os dados prometem cumprir — unicidade da chave, intervalos válidos, percentagem máxima de nulos, integridade referencial.
- SLA e frescura. Com que frequência os dados são atualizados, qual a latência esperada e o que acontece quando uma carga falha ou chega atrasada.
- Propriedade. Quem é responsável pelo conjunto de dados, como contactar essa equipa e por onde são comunicadas as mudanças.
- Versão. Um número de versão que permite evoluir o contrato de forma controlada, distinguindo mudanças compatíveis de mudanças que partem consumidores.
Na prática, isto costuma viver num ficheiro estruturado — YAML ou JSON — guardado no repositório junto ao pipeline que produz os dados. O formato importa menos do que o princípio: o contrato é código, revisto como código e testado como código.
Contrato, catálogo e governança: o que é diferente
É fácil confundir contratos de dados com iniciativas próximas, mas o foco é distinto. Um catálogo de dados descreve o que existe — ajuda a descobrir tabelas e a perceber o seu conteúdo. Um contrato vai mais longe: garante que aquilo que existe se comporta como prometido, e falha o build quando não se comporta.
A governança de dados, por sua vez, define políticas ao nível da organização: quem pode aceder a quê, como se classifica informação sensível, que regras de retenção se aplicam. O contrato é o mecanismo concreto que operacionaliza parte dessa governança no ponto onde os dados mudam de mãos. Não competem — completam-se. O catálogo torna os dados descobríveis, a governança define as regras, e o contrato torna as promessas verificáveis no dia a dia.
Como implementar na prática
O que distingue um contrato de dados de uma boa intenção é a verificação automática. Sem enforcement, um contrato é apenas documentação — e a documentação diverge sempre da realidade. A ideia central é simples: sempre que o produtor tenta publicar dados que violam o contrato, o processo falha antes de esses dados chegarem aos consumidores.
Isto costuma materializar-se em dois pontos. Primeiro, no CI/CD do lado do produtor: uma alteração ao pipeline que quebre o schema declarado não passa nos testes e não é integrada. Segundo, em tempo de execução: cada carga é validada contra o contrato e, se falhar uma regra de qualidade, os dados são retidos em quarentena em vez de propagados. Ferramentas de teste e de validação de schema tornam isto acessível sem construir tudo de raiz, e plataformas de transformação como o dbt permitem declarar e testar expectativas junto às próprias transformações.
O ponto essencial não é a ferramenta, é a mudança de responsabilidade: o produtor deixa de poder alterar os dados em silêncio. A promessa passa a ter consequências no momento em que é quebrada, e não semanas depois, num relatório errado.
Evoluir o contrato sem partir quem consome
Um contrato não é uma jaula. Os dados evoluem, e o contrato tem de evoluir com eles — a questão é fazê-lo sem apanhar os consumidores de surpresa. A distinção decisiva é entre mudanças compatíveis e mudanças que partem.
Adicionar uma coluna nova é, quase sempre, uma mudança compatível: quem já consumia continua a funcionar. Já remover uma coluna, mudar o seu tipo ou alterar o significado de um valor é uma mudança que parte — e exige um processo. Esse processo costuma passar por versionar o contrato, anunciar a nova versão com antecedência, manter a versão antiga durante um período de transição e só depois desativar a antiga. É exatamente o que uma equipa de software faz quando descontinua uma versão de API.
Tratar a evolução com esta disciplina transforma a relação entre equipas. Em vez de mudanças unilaterais seguidas de incêndios, há um canal previsível: quem produz sabe que pode evoluir, e quem consome sabe que terá aviso e tempo para se adaptar.
Mini-caso: uma empresa de retalho
Considere-se uma empresa de retalho com loja física e online, cujo departamento de dados alimentava cerca de quarenta relatórios a partir de tabelas partilhadas pela equipa de e-commerce. Numa atualização da plataforma de loja, o campo que indicava o valor da encomenda passou a incluir o IVA, quando antes o excluía. Nada no schema mudou — o tipo continuou a ser decimal — e por isso nenhum teste técnico acusou o problema.
Durante onze dias, os relatórios de receita sobreavaliaram as vendas em cerca de 23%, e as decisões de reposição de stock foram tomadas com base nesses números. Quando a discrepância foi finalmente detetada, corrigir os relatórios e reconstruir o histórico afetado consumiu quase duas semanas de trabalho de duas pessoas.
A resposta não foi comprar uma ferramenta cara, mas introduzir um contrato para as três tabelas mais críticas do e-commerce. O contrato declarava explicitamente que valor_encomenda excluía IVA e incluía uma verificação de intervalo por artigo. Meses depois, uma mudança semelhante voltou a ser tentada a montante — desta vez, o build falhou no mesmo dia, com uma mensagem clara, e a equipa corrigiu antes de qualquer relatório ser afetado. O custo do contrato foi de alguns dias de trabalho; o custo evitado, semanas recorrentes.
Erros comuns e por onde começar
A forma mais rápida de fazer fracassar uma iniciativa de contratos de dados é tentar contratualizar tudo ao mesmo tempo. Isso gera centenas de ficheiros que ninguém mantém e uma sensação de burocracia que afasta as equipas. Alguns erros recorrentes, e como evitá-los:
- Começar pela ferramenta e não pela dor. Identifique primeiro os conjuntos de dados cuja quebra causa mais estragos e comece por esses.
- Contratos sem enforcement. Um contrato que não falha o build é apenas documentação que vai divergir da realidade. A verificação automática é o que lhe dá valor.
- Esquecer a semântica. Validar tipos é fácil; o que parte relatórios são as mudanças de significado. Documente unidades, moeda e definições de negócio.
- Não definir dono. Sem propriedade clara, ninguém mantém o contrato nem responde quando ele falha.
Por onde começar, então: escolha um ou dois conjuntos de dados críticos, escreva um contrato mínimo que cubra schema, semântica e duas ou três regras de qualidade, e ligue-o à verificação automática. Demonstre o valor numa quebra evitada e deixe a adoção crescer a partir daí.
Na prática
Contratos de dados não são uma tecnologia nova a instalar, mas uma disciplina a adotar: tornar explícitas, versionadas e verificáveis as promessas que já existem implicitamente entre equipas. O retorno não está em impressionar com arquitetura, mas em evitar a classe de falhas que corrói silenciosamente a confiança nos dados.
Comece pequeno, no ponto onde mais dói, com verificação automática desde o primeiro dia. Um único contrato que apanhe uma quebra antes de ela chegar a um relatório costuma pagar, sozinho, todo o esforço de o criar. A partir daí, a pergunta deixa de ser quem mexeu nestes dados e passa a ser que versão do contrato queremos para o próximo trimestre.
