Shift schema drift left: policy-aware compile-time contracts for typed JVM and Spark pipelines

Este artigo apresenta um pequeno framework em Scala 3 que une verificações de compatibilidade estrutural em tempo de compilação com validações de política em tempo de execução para detectar e prevenir a deriva de esquema (schema drift) em pipelines JVM e Spark antes da escrita dos dados.

O essencial

Imagine que você é o gerente de uma grande fábrica de alimentos (o pipeline de dados). O seu trabalho é pegar ingredientes crus, processá-los e colocar o produto final em caixas para envio.

O problema é que, às vezes, o fornecedor muda o formato dos ingredientes sem avisar: em vez de "maçãs", enviam "peras", ou trocam a ordem das frutas na caixa. Se você só descobrir isso quando o caminhão chega na loja (o momento da escrita dos dados), o produto já está estragado e o cliente está insatisfeito.

Este artigo apresenta uma nova ferramenta para evitar esse desastre, combinando duas etapas de segurança: uma antes de começar a produção e outra na porta de saída.

Aqui está a explicação simples, usando analogias do dia a dia:

1. O Problema: "A Surpresa na Entrega"

Na maioria das fábricas de dados atuais, os engenheiros escrevem o código pensando em um formato específico (ex: "vamos receber uma lista de usuários com nome e idade"). Mas, na vida real, os dados vêm de fontes externas (arquivos CSV, JSON, bancos de dados) que podem mudar a qualquer momento.

• O risco: O código parece perfeito no computador do programador, mas quando roda de verdade, os dados chegam bagunçados e o sistema quebra.

2. A Solução: O "Duplo Checagem" Inteligente

O autor criou uma ferramenta (um pequeno framework em Scala) que faz duas coisas diferentes, mas que trabalham juntas:

A. O "Checador de Receitas" (Tempo de Compilação)

Imagine que, antes de você começar a cozinhar, você tem um chef de cozinha robótico que lê a sua receita e a lista de ingredientes que o fornecedor prometeu enviar.

• Como funciona: Se a receita diz "preciso de 3 ovos" e o fornecedor prometeu "2 ovos", o robô não deixa você nem começar a cozinhar. Ele para tudo e diz: "Ei, falta um ovo! Corrija a receita ou o pedido antes de ligar o fogão."
• A mágica: Isso acontece antes de você gastar tempo ou dinheiro. O código nem sequer é transformado em um programa executável se houver erro. É como ter um contrato escrito que o computador lê e garante que está tudo certo.

B. O "Guarda da Porta" (Tempo de Execução)

Mas e se o fornecedor mentiu? E se ele prometeu 3 ovos, mas no caminhão real só trouxeram 2? O robô da cozinha não pode ver o caminhão real, só a promessa escrita.

• Como funciona: Quando o produto final está pronto para entrar no caminhão (antes de ser enviado para o cliente), um guarda da porta olha a carga real.
• A mágica: Ele compara o que realmente está no caminhão com o que foi prometido no contrato. Se houver uma diferença perigosa (como uma fruta estragada que o robô não viu), ele bloqueia a saída. Nada sai da fábrica se não estiver seguro.

3. As "Regras do Jogo" (Políticas)

O que torna essa ferramenta especial é que ela permite definir quão rígidas devem ser as regras. É como escolher o nível de segurança de um aeroporto:

• Regra Rígida (Exata): "Só entra se for exatamente igual. Nem uma vírgula a mais, nem uma menos."
• Regra Flexível (Subconjunto): "Se o fornecedor enviar mais coisas do que pedimos, tudo bem (nós ignoramos o extra). Mas se faltar algo essencial, não entra."
• Regra de Ordem: "A ordem dos ingredientes importa?" (Às vezes sim, às vezes não).

A ferramenta permite que você escolha essa regra para cada porta de saída da sua fábrica.

4. Por que isso é importante?

Antes dessa ferramenta, as empresas tinham que escolher entre dois extremos:

1. Reescrever tudo: Usar sistemas muito complexos que exigem mudar todo o código da fábrica para algo "tipado" (muito caro e difícil).
2. Confiar na sorte: Deixar os dados entrarem e esperar que nada quebre quando o cliente reclamar.

Esta ferramenta é o meio-termo inteligente. Ela não exige que você reescreva toda a sua fábrica. Ela apenas coloca um "selo de qualidade" na porta de entrada (no código) e um "guarda" na porta de saída (nos dados reais).

Resumo da Ópera

Pense nisso como um sistema de segurança em duas camadas:

1. Na teoria (antes de rodar): O computador garante que o plano está correto.
2. Na prática (na hora de enviar): O sistema garante que a realidade bate com o plano.

O autor é honesto: essa ferramenta não resolve todos os problemas do mundo (como regras de negócio complexas ou lógica de "se o preço subir, o estoque deve cair"). Ela foca apenas em garantir que a forma dos dados (o formato da caixa) esteja correta. Mas, para evitar que a fábrica pare por causa de uma caixa torta, essa é uma solução brilhante, barata e rápida.

Em suma: É como ter um contrato que o computador lê antes de você começar a trabalhar e um guarda que verifica a carga antes de você sair de casa. Assim, você evita surpresas desagradáveis no caminho.

---

O Truque Especial: A maioria dos inspetores só verifica a caixa principal. Este inspetor verifica um detalhe específico no interior: se cada espaço em uma lista ou mapa aninhado pode estar vazio ou não. Por exemplo, se o contrato diz "uma caixa de maçãs onde cada espaço deve estar preenchido" mas o caminhão envia "uma caixa de maçãs onde alguns espaços estão vazios", este inspetor detecta o erro. Ferramentas padrão frequentemente perdem essas discrepâncias de opcionalidade profundas dentro de listas e mapas.

Resumo técnico

Título do Artigo

Shift schema drift left: policy-aware compile-time contracts for typed JVM and Spark pipelines
(Deslocar a derivação de esquema para a esquerda: contratos em tempo de compilação conscientes de políticas para pipelines tipados JVM e Spark)

Autor: Vittal Mirji (Staff Software Engineer)

---

1. O Problema

A derivação de esquema (schema drift) em pipelines de dados é frequentemente detectada apenas quando um job processa dados reais, o que pode levar a falhas em produção. As soluções existentes apresentam lacunas:

• Camadas de Dataset Tipado (ex: frameless, iskra): Exigem a substituição de todo o código Spark por wrappers tipados, o que gera um alto custo de adoção.
• Aplicação de Esquema em Nível de Tabela (ex: Delta Lake, Iceberg): Operam no momento da escrita (write-time) contra um esquema armazenado, mas não contra o tipo declarado no código Scala. Isso significa que a verificação ocorre após a submissão do job.
• Comparadores Nativos do Spark: Realizam verificações em tempo de execução, mas não oferecem prova de compatibilidade estrutural antes da compilação e ignoram certas nuances, como a opcionalidade de coleções aninhadas.

O artigo identifica uma "costura" (seam) não coberta: a falta de uma prova em tempo de compilação de que um tipo de produtor declarado é compatível com um tipo de contrato sob uma política explícita, combinada com uma verificação em tempo de execução na fronteira do sink.

2. Metodologia e Design do Framework

O autor apresenta um pequeno framework em Scala 3 que ocupa essa lacuna através de uma abordagem híbrida:

A. Modelo de Contrato Estrutural

O contrato é definido estritamente como a forma estrutural do registro (nomes de campos, aninhamento, tipo de coleção, opcionalidade e valores padrão), excluindo regras de negócio semânticas.

• Família de Políticas: O sistema permite definir explicitamente como a compatibilidade deve ser verificada:
  • Exatas: Exact, ExactUnorderedCI (ignora ordem, case-insensitive), ExactOrdered, ExactByPosition.
  • Subconjunto: Backward (produtor pode ter campos extras; faltantes no contrato só são aceitos se opcionais/padrão), Forward (produtor deve ter todos os campos do contrato).
  • Full: Aceita todas as combinações.

B. Camada de Compilação (Prova Estrutural)

• Utiliza Macros Scala 3 e reflexão citada (quoted reflection) para inspecionar tipos case class.
• Normaliza os tipos Scala em um modelo interno (TypeShape) que captura nomes, aninhamento e opcionalidade.
• Deriva um testemunho de tipo (SchemaConforms[Out, Contract, P]) em tempo de compilação. Se o produtor não for compatível com o contrato sob a política escolhida, a compilação falha com relatórios de erro ricos e detalhados.

C. Camada de Runtime (Pino de Verificação)

• Deriva um esquema Spark StructType diretamente do mesmo tipo de contrato Scala usado na compilação, evitando duplicação manual.
• Implementa um comparador consciente de políticas na fronteira de escrita (sink boundary).
• Diferencial Crítico: O comparador runtime verifica explicitamente a opcionalidade de coleções aninhadas (ex: Option dentro de um Array), uma verificação que os comparadores nativos do Spark ignoram por padrão.
• Aplica semântica de subconjunto real para políticas Backward e Forward.

D. Construtor Tipado (Typed Builder)

O framework utiliza um construtor com disciplina de typestate (parâmetro fantasma) que exige a evidência de compilação (SchemaConforms) no momento de adicionar um sink (addSink[R, P]). Isso garante que a prova e a verificação runtime estejam intrinsecamente ligadas ao mesmo ponto de fronteira.

3. Contribuições Principais

1. Derivação Macro em Scala 3: Geração de testemunhos de compatibilidade estrutural em tempo de compilação com diagnósticos detalhados de derivação, rejeitando pares incompatíveis antes da execução.
2. Design de Fronteira de Sink Híbrido: Fusão da prova de compilação com um comparador runtime consciente de políticas, incluindo a verificação de opcionalidade de coleções aninhadas e semântica de subconjunto (Backward/Forward) que o Spark nativo não fornece.
3. Artefato Reprodutível: Uma implementação de referência pequena e honesta que demonstra que essa combinação pode ser realizada com baixo custo de compilação e um custo de runtime mensurável (microssegundos por comparação).

4. Resultados e Avaliação

A avaliação focou na correção mecânica e no custo, não em métricas industriais de produtividade:

• Cobertura: O sistema valida corretamente casos positivos e rejeita casos negativos (reordenação, campos faltantes, derivação de opcionalidade aninhada) tanto em compilação quanto em runtime.
• Overhead de Compilação: Adicionou entre 0,27s e 1,88s ao tempo de compilação (dependendo do ambiente e número de pares de esquemas), o que é considerado aceitável para a segurança ganha.
• Overhead de Runtime:
  • Comparadores por posição: ~116-180 ns.
  • Comparadores exatos não ordenados: ~4.700-8.100 ns.
  • Embora seja mais lento que os comparadores nativos do Spark (17-25x), o custo permanece na faixa de microssegundos e é executado apenas uma vez por escrita de sink, não por linha de dados.
• Validação: Os testes end-to-end confirmaram que o construtor tipado impede a compilação se a prova falhar e rejeita a escrita em runtime se o esquema real dos dados violar a política, mesmo que o código Scala estivesse correto.

5. Significado e Limitações

Significado:
O artigo demonstra que é possível "deslocar para a esquerda" (shift left) a detecção de derivação de esquema para a fase de compilação e CI/CD, sem exigir a reescrita completa de pipelines Spark para usar bibliotecas tipadas pesadas. Ele estabelece que a verificação estrutural e a verificação semântica de runtime são complementares, não redundantes.

Limitações:

• Escopo Estrito: O framework verifica apenas compatibilidade estrutural, não regras de negócio, invariantes temporais ou restrições de domínio.
• Cobertura de Formas: Foca em case classes, sequências, mapas e opcionalidade, não cobrindo todo o espectro de representações de dados Spark/Scala.
• Evidência Industrial: Não há integração com registros de esquema externos nem estudos de caso de adoção em larga escala. O artigo é uma "prova de conceito mecânica" honesta, deixando para trabalhos futuros a medição de ganhos de produtividade e confiabilidade em escala industrial.

Em resumo, o trabalho oferece um mecanismo prático e verificável para garantir a integridade de esquemas em pipelines Scala/Spark, combinando a segurança estática da compilação com a proteção dinâmica na fronteira de dados.