Neste artigo
Spoiler: o pipeline não quebrou porque o modelo piorou. Quebrou porque alguém renomeou uma coluna na tabela de eventos e ninguém avisou ninguém.
Isso é muito mais comum do que parece. Times pequenos com dados em produção vivem numa situação específica: o stack cresce rápido, mas os acordos sobre como os dados fluem entre sistemas ficam na cabeça de uma ou duas pessoas. Enquanto o time é pequeno, funciona. Quando o primeiro engenheiro sai de férias ou a tabela de origem muda por qualquer razão, o pipeline de ML some silenciosamente e o dashboard mostra zeros por três dias antes de alguém perceber.
Data contracts são a resposta para isso. Não a resposta miraculosa, mas a que funciona quando implementada com critério. Vou explicar o que são, por que importam mais do que parecem e como um time pequeno pode adotar sem virar a vida de cabeça para baixo.
O problema real: falhas silenciosas upstream
Na minha experiência, a maioria dos problemas em pipelines de ML e analytics não está no modelo. Está nos dados que chegam nele. E o pior tipo de problema não é o que quebra com erro explícito. É o que passa sem ruído e contamina resultados por semanas.
Pensa no cenário: você tem um modelo que prevê churn com base em eventos de uso. O time de produto adiciona um novo tipo de evento com nomenclatura diferente. A tabela de origem muda. Seu pipeline lê a coluna antiga, que agora vem nula, e o modelo começa a prever que todo mundo vai sair. Nenhum erro foi lançado. A métrica de monitoramento do modelo pode até parecer estável se você não estiver olhando para a distribuição dos inputs.
Esse problema tem nome: ausência de contrato entre quem produz os dados e quem consome. Times pequenos são especialmente vulneráveis porque a comunicação acontece de forma informal. Alguém faz uma migração, avisa no Slack, mas o pipeline não sabe disso.
O que é um data contract de verdade
Um data contract é um acordo formal sobre a estrutura, semântica e qualidade dos dados que um sistema produz para outro consumir. Ele define quais campos existem, quais tipos são esperados, quais valores são válidos, qual a frequência de atualização esperada e quem é responsável por manter isso.
Na prática, pode ser um schema definido em arquivo de configuração, um conjunto de validações automáticas ou um artefato versionado que qualquer parte do pipeline pode checar antes de continuar. O formato importa menos do que o princípio: o produtor dos dados se compromete com uma interface, e o consumidor valida que essa interface está sendo respeitada.
A diferença entre um data contract e uma documentação de dados é essa: documentação é passiva. Ninguém sabe quando ficou desatualizada. Um data contract é ativo, valida em runtime e quebra de forma visível quando a interface foi violada. Prefiro muito o ruído explícito ao silêncio que contamina resultados.
Por que times pequenos precisam mais, não menos
Existe uma percepção de que data contracts são coisa de empresa grande com engenharia de dados madura. Na minha experiência, é o contrário. Times pequenos são mais vulneráveis porque:
- Mudanças nos dados de origem acontecem sem processo formal de revisão
- Não há equipe dedicada a monitorar qualidade de dados continuamente
- Um único engenheiro costuma manter o pipeline, o modelo e o dashboard ao mesmo tempo
- A comunicação entre times é menos estruturada, o que aumenta o risco de mudanças não comunicadas
Não é que times pequenos devam implementar algo mais leve. É que devem implementar algo fácil de manter com pouca gente, mas robusto o suficiente para pegar os casos críticos.
Como implementar sem complicar
A abordagem que funciona bem para times pequenos tem três camadas: validação de schema na entrada do pipeline, assertions de qualidade nos dados transformados e versionamento com comunicação de mudanças.
Camada 1: validação de schema na entrada
Antes de processar qualquer dado, valide que a estrutura está como esperado. Você define quais colunas devem existir, quais tipos são esperados e quais restrições se aplicam, como campos não nulos ou valores dentro de um conjunto permitido. Se a tabela de origem renomear uma coluna ou mudar um tipo, a validação quebra antes de processar. Você sabe na hora, não três dias depois.
Para implementar isso com ajuda de uma IA, descreva a estrutura da tabela que você precisa validar: nome de cada campo, tipo esperado, se pode ser nulo e quais valores são válidos quando aplicável. Com essa descrição, a IA consegue gerar o schema de validação em qualquer biblioteca de sua escolha, como Pandera para DataFrames do pandas ou Pydantic para dados em dicionário.
Camada 2: assertions de qualidade nos dados transformados
Schema correto não significa dados corretos. Um campo pode estar no tipo certo mas com valores fora do esperado. Aqui entram as assertions de qualidade. O que você define depende do contexto, mas alguns exemplos práticos:
- Volume: número de registros por dia dentro de uma faixa esperada. Desvio acima de um percentual definido dispara alerta
- Nulidade: campos críticos não podem ter taxa de nulo acima de um limite definido
- Distribuição: média ou mediana de campos numéricos não pode desviar mais de um número de desvios padrão da janela histórica
- Unicidade: identificadores de entidade devem ser únicos dentro do batch
Ferramentas como Great Expectations oferecem framework completo com documentação automática das expectativas. Para times menores que não querem esse overhead, assertions escritas diretamente no pipeline resolvem bem o essencial.
Camada 3: versionamento e comunicação de mudanças
O contrato precisa viver em algum lugar versionado. Um arquivo de configuração por fonte de dados com os campos esperados, tipos e regras de qualidade já é suficiente para começar. Quando alguém precisa mudar a estrutura da tabela de origem, a primeira pergunta passa a ser qual a versão atual do contrato e quem precisa ser notificado.
Isso muda o processo de mudança de informal para rastreável. Parece burocracia. Na prática, é o que diferencia um incidente de dois minutos de um incidente de dois dias.
Como saber se funcionou
Implementar data contracts sem medir o impacto é cair no mesmo problema que você tentava resolver. As métricas que fazem sentido acompanhar:
- Tempo médio para detecção de quebra de pipeline: quanto tempo leva desde a mudança na fonte até você saber que algo quebrou. Antes dos contratos, esse número costuma ser medido em dias. Com contratos ativos, deve cair para minutos ou horas
- Número de incidentes silenciosos por trimestre: quebras que você descobriu por efeito colateral, como dashboard errado ou métrica de negócio fora do lugar, ao invés de alerta do pipeline. Esse número deve ir a zero
- Taxa de violação de contrato por fonte: quantas vezes cada fonte de dados violou o contrato no período. Fontes com taxa alta são candidatas a revisão ou conversa com o time produtor
Se você implantou data contracts e o tempo de detecção não mudou, o problema pode estar na integração com o sistema de alerta. Se a taxa de violação é zero desde o primeiro dia, o contrato provavelmente está permissivo demais.
Limitações que vale dizer antes
Data contracts não resolvem dados ruins que chegam dentro do schema esperado. Se o produtor começa a enviar eventos duplicados mas o schema de tipos continua correto, o contrato passa. Por isso a camada de assertions de qualidade é importante além da validação de schema pura.
Também não resolvem o problema de semântica. Um campo chamado receita pode ser bruta num contexto e líquida em outro, e o schema não vai detectar isso. O contrato precisa incluir documentação da definição dos campos, não só tipos técnicos.
Por fim, contratos têm custo de manutenção. Quando a interface muda de forma legítima, alguém precisa atualizar o contrato e garantir que os consumidores estão adaptados. Em times pequenos, esse processo precisa ser leve, senão o contrato fica desatualizado e perde a função. Vale revisar os contratos das fontes críticas a cada trimestre.
Dúvidas comuns sobre data contracts
Data contract é diferente de schema de banco de dados?
Sim. O schema do banco define como os dados são armazenados. O data contract define o que o consumidor pode esperar receber, incluindo regras de qualidade, frequência de atualização e responsável pela manutenção. O schema é uma parte do contrato, não o contrato inteiro.
Preciso de ferramenta específica para implementar?
Não. Um arquivo de configuração no Git com os campos esperados e suas regras, combinado com validação implementada na entrada do pipeline, já é um data contract funcional. Ferramentas como Great Expectations ou Soda adicionam interface, documentação automática e integração com outras ferramentas, mas não são pré-requisito para começar.
O que faço quando o contrato é violado?
Depende da criticidade. Para campos obrigatórios em modelo de produção, o pipeline deve parar e gerar alerta imediato. Para campos secundários, pode ser uma flag nos logs para revisão posterior. O importante é ter essa decisão tomada quando você define o contrato, não no momento do incidente.
Como data contracts se relacionam com monitoramento de modelo?
Dados de entrada dentro do contrato não garantem que o modelo está se comportando bem. Você ainda precisa monitorar as saídas do modelo. O contrato cobre a camada upstream, garantindo que os dados chegam com a estrutura esperada. Para a camada de qualidade das respostas do modelo, o artigo sobre quando retreinar um modelo de IA cobre os sinais que antecipam degradação.
Conclusão e próximo passo
Data contracts na prática não são burocracia. São a diferença entre descobrir uma quebra de pipeline em minutos ou em dias. Para times pequenos com dados em produção, o investimento em contratos ativos é menor do que o custo de um incidente silencioso que contamina resultados por semanas sem que ninguém perceba.
Se você quer avançar com isso, o próximo passo é:
- Identificar as duas ou três fontes de dados que alimentam os sistemas mais críticos
- Mapear os campos que você usa de cada fonte e os tipos esperados
- Adicionar validação de schema como primeira etapa do pipeline para pelo menos uma dessas fontes
Para entender como construir um sistema de análise de dados confiável como base para esses contratos, o artigo sobre DuckDB e Polars na prática cobre como trabalhar com dados locais sem stack exagerada. E para monitorar o que acontece depois que os dados passam pelo contrato e chegam no modelo, o artigo sobre como monitorar custo e latência de LLMs cobre a camada de observabilidade da aplicação.
