20 min
Contrato da fonte
A fronteira da extração, o perfil da origem e a semântica de atualização.
Contrato da fonte, estratégias de captura e idempotência, com a construção de uma extração incremental sobre uma origem transacional que sofre atualização e exclusão.
Computação 1 · Prof. Hermano Peixoto · 09/09/2026
Continuidade · da Aula 10 para a Aula 12
A Aula 10 decidiu onde e como o dado fica guardado. Esta aula trata de como ele entra, com que garantias e sob qual possibilidade de reprocessamento.
Roteiro · 120 minutos · uma hora de exposição, uma hora de prática
A segunda hora é atividade em grupo: extrair de uma origem transacional que sofre atualização e exclusão, e medir o que cada estratégia perde.
A fronteira da extração, o perfil da origem e a semântica de atualização.
Full load, incremental por watermark, CDC e idempotência.
Paginação, retry, chegada atômica, controle e replay.
Extração incremental sobre Postgres, com mutações que a quebram.
Bloco 1 · A fronteira
Antes dessa fronteira, o dado obedece às regras de quem o produz. Depois dela, a responsabilidade pela completude e pela rastreabilidade é do pipeline.
O sistema transacional otimiza a escrita e o atendimento ao usuário. A leitura analítica compete por recurso, e a origem pode limitar, atrasar ou recusar a extração sem aviso. A janela de disponibilidade integra o contrato.
A extração que termina sem erro pode ter trazido metade dos registros. A verificação se faz por contagem reconciliada com a origem, e não pelo encerramento do processo.
Bloco 1 · Perfil da fonte
Nove atributos determinam a estratégia de extração. Levantá-los depois da implementação custa a reescrita do pipeline.
Responsável pela origem e canal de comunicação em caso de mudança.
Chave natural que identifica o registro de forma estável ao longo do tempo.
Semântica de atualização: a origem corrige a linha, ou insere uma nova?
Exclusão física ou lógica, e como ela é observável de fora.
Timezone dos carimbos de tempo e se há horário de verão na série.
Janela de disponibilidade: quando a origem aceita carga de leitura.
Limites de requisição, de volume por página e de tempo de conexão.
Campos sensíveis, classificados antes da primeira extração.
Volume e crescimento, que determinam se o full load continua viável.
Bloco 1 · Semântica de atualização
Três comportamentos distintos, com consequências opostas para a estratégia de extração.
Cada fato gera uma linha nova, e a correção entra como novo registro. É o caso mais simples: o incremental por carimbo de tempo captura tudo.
Estratégia: incremental por timestamp de criação.
O registro muda de estado sem mudar de identidade. A captura depende de um campo de atualização que a origem mantenha de forma disciplinada em toda escrita.
Estratégia: incremental por timestamp de atualização, com verificação periódica.
O registro desaparece sem deixar rastro consultável. Nenhuma consulta ao estado atual revela o que existia antes, porque não há o que ler.
Estratégia: captura pelo log de transações, ou reconciliação periódica de chaves.
Bloco 1 · Tipos de origem
O que se negocia com quem mantém a origem, e como a extração degrada quando o contrato não é cumprido.
| Origem | O que precisa ser negociado | Modo de falha característico | Defesa correspondente |
|---|---|---|---|
| Banco relacional | Réplica de leitura, janela e acesso ao log | A consulta analítica concorre com a transação e é interrompida | Extrair da réplica, em janela acordada e com lote limitado |
| API | Limite de requisições, paginação e contagem declarada | Página vazia devolvida por limite, interpretada como fim | Validar pela contagem declarada e aplicar retry com backoff |
| Arquivo | Convenção de nome, checksum e sinal de conclusão | Leitura do arquivo enquanto ele ainda está sendo gravado | Separar landing de processamento e mover após o checksum |
| Evento | Schema registrado, retenção e garantia de entrega | Reentrega do mesmo evento após falha parcial | Ingestão idempotente por chave natural e janela |
Bloco 2 · Estratégias de extração
O volume determina o custo, e a semântica de atualização determina a corretude. A segunda restringe a primeira.
custo alto · corretude alta
custo baixo · corretude condicional
custo médio · corretude alta
Bloco 2 · Watermark
É um valor persistido, avançado apenas quando o lote inteiro conclui. A janela seguinte parte dele, com sobreposição deliberada.
O evento gravado na origem no instante da virada da janela pode não estar visível quando a extração lê. A sobreposição de alguns minutos recupera esse registro, e a deduplicação por chave natural remove a repetição resultante.
Avançar a marca antes de a gravação concluir cria uma lacuna permanente: a janela seguinte parte de um ponto cujo conteúdo nunca foi persistido, e nenhuma execução posterior o alcança.
Bloco 2 · Divergência
As três produzem destino incorreto sem emitir erro, e é isso que as torna difíceis de detectar em produção.
| Evento na origem | O que a extração observa | Efeito no destino | Correção |
|---|---|---|---|
| Exclusão física | A linha desaparece, sem alteração de carimbo | O registro permanece no destino indefinidamente | Captura pelo log, ou reconciliação de chaves por anti-junção |
| Atualização sem carimbo | Nada, porque o campo de controle não se moveu | O destino guarda o valor anterior como se fosse o vigente | Gatilho na origem, ou reconciliação periódica por full load |
| Escrita retroativa | Um registro com carimbo anterior à marca d'água | O registro nunca entra, porque a janela já passou daquele ponto | Separar data do evento da data de ingestão e filtrar pela segunda |
Bloco 2 · Captura pelo log
O banco já grava cada escrita em um log para garantir durabilidade e recuperação. A captura de mudanças lê esse mesmo log.
Confirme a retenção do log na origem: ela define a janela máxima de replay.
Garanta ordenação por chave: as operações do mesmo registro precisam chegar em ordem.
Trate o consumo como ao menos uma vez e torne a aplicação idempotente.
Planeje a carga inicial: o log cobre o presente, e o passado exige um instantâneo.
Negocie o acesso privilegiado: a leitura do log exige permissão que o DBA controla.
Monitore o atraso de consumo: log não consumido é log que expira e vira lacuna.
Bloco 2 · Idempotência
É a propriedade que torna o replay seguro, e sem ela nenhuma falha parcial pode ser corrigida por repetição.
A chave identifica o registro, a ordenação decide qual versão prevalece e a regra de desempate resolve o empate de forma determinística. Sem os três declarados, duas execuções da mesma janela produzem resultados distintos.
Cada execução recebe um identificador, e o registro guarda de qual lote veio. O reprocessamento se torna uma operação declarada, com efeito conhecido antes de ser executada.
Bloco 3 · APIs
O código de status informa que a requisição foi atendida, e nada declara sobre quantos registros deveriam ter vindo.
Encerre a paginação pela contagem total declarada ou pelo cursor de continuação, e não pela primeira página vazia. O limite de requisições devolve página vazia com status de sucesso.
A repetição imediata agrava a sobrecarga que causou a recusa. O intervalo entre tentativas cresce a cada falha, com variação aleatória para evitar que todos os consumidores repitam no mesmo instante.
Grave a resposta como veio, antes de qualquer conversão. Quando o formato mudar ou a interpretação se revelar errada, o reprocessamento parte do original em vez de exigir nova extração.
Bloco 3 · Arquivos
A chegada de um arquivo é um processo com duração, e a leitura durante esse intervalo produz carga parcial que se apresenta como bem-sucedida.
Separe landing de processamento, e mova o arquivo apenas após verificar o checksum.
Exija sinal de conclusão: arquivo auxiliar ou renomeação atômica ao terminar a gravação.
Valide encoding, delimitador e schema antes de processar, e rejeite com motivo registrado.
Detecte reenvio pelo checksum: o mesmo arquivo entregue duas vezes não deve duplicar o destino.
Trate coluna nova como evento de governança, com decisão registrada e não como falha.
Uma coluna acrescentada, renomeada ou reordenada altera a interpretação de todo o arquivo. A extração posicional quebra em silêncio: o valor de uma coluna passa a ser lido como se fosse de outra, e a carga conclui sem erro.
Defesa: leitura por nome de coluna, validação do schema contra o contrato registrado e alerta quando a diferença aparece.
Bloco 3 · Operação
A tabela de controle transforma a extração em operação auditável, com estado consultável e replay previsível.
Segunda hora · Card de trabalho em sala
Em grupo, sobre a origem montada em sala: extrair, sofrer mutações e medir o que cada estratégia deixou passar.
Compare o destino do incremental com o de um full load posterior às mutações. A diferença é um número a explicar.
Identifique por anti-junção as chaves do destino ausentes na origem, e declare o efeito sobre a receita.
Execute a mesma janela duas vezes e compare a contagem. A carga é idempotente quando os dois números coincidem.
Segunda hora · Arquitetura
O lakehouse da Aula 10 permanece como destino. O que se acrescenta é uma origem viva, que sofre inserção, atualização e exclusão durante o encontro.
O arquivo CSV é imutável e não permite observar o que acontece quando a origem corrige e apaga registros. O banco transacional torna a divergência reproduzível em sala, com número medido em vez de descrição.
O bucket, a convenção de prefixo e o formato Parquet permanecem. A aula acrescenta ao lakehouse a camada de controle e o carimbo de lote, sem refazer o ambiente.
Segunda hora · Preparação · 10 minutos
Um container e um bloco de configuração. O MinIO da Aula 10 permanece como está.
Segunda hora · Full load · 10 minutos
Executada uma vez, antes de qualquer mutação, ela define o estado correto contra o qual as estratégias seguintes serão medidas.
Segunda hora · Incremental · 15 minutos
Cada grupo implementa a janela, a sobreposição e o avanço condicionado da marca d'água.
Segunda hora · Mutações · 15 minutos
Execute o bloco abaixo na origem, rode o incremental de novo e meça. Os três casos são deliberados e os números são conferíveis.
O carimbo se moveu, a janela alcança as linhas e o destino recebe o novo estado.
O carimbo permaneceu no valor anterior, e nada indica à extração que a linha mudou.
A linha não existe mais na origem, e nenhuma consulta ao estado atual pode revelá-la.
Segunda hora · Correção · 10 minutos
Sem acesso ao log de transações, a defesa disponível é comparar periodicamente o conjunto de chaves da origem com o do destino.
Marcar a exclusão preserva o histórico e permite responder desde quando o pedido deixou de existir. Remover a linha alinha o destino ao estado atual e apaga a informação. A escolha é de negócio, e precisa estar declarada.
A comparação de chaves tem custo próximo ao do full load. Por isso ela é periódica, e não a cada execução. A frequência se define pela tolerância a divergência declarada no requisito não funcional.
Segunda hora · Replay
A verificação encerra o laboratório e é a prova de que a extração pode ser reprocessada sem intervenção manual.
Segunda hora · Conferência
Números esperados em cada etapa, sobre a tabela de pedidos da Olist com as mutações do slide anterior aplicadas.
| Etapa | O que verificar | Referência |
|---|---|---|
| Origem carregada | Contagem na tabela do Postgres | 99 441 pedidos, idênticos ao CSV |
| Full load | Contagem gravada na bronze | 99 441, com um único batch_id |
| Após as mutações | Contagem na origem | 99 241, com 200 excluídos fisicamente |
| Incremental | Linhas trazidas pela janela | Ordem de 500, correspondentes ao caso A |
| Reconciliação | Anti-junção e comparação de estado | 200 chaves ausentes e 300 estados divergentes |
| Replay | Contagem antes e depois da reexecução | Idêntica, com dois lotes na tabela de controle |
Segunda hora · Uso de IA · em paralelo
O assistente acelera a escrita do SQL e do controle. A conferência dos números permanece atribuição do grupo e determina a correção do resultado.
"Este é o schema da tabela de pedidos. Liste as perguntas que preciso responder sobre a origem antes de escolher entre full load, incremental por carimbo e captura pelo log."
"Escreva SQL DuckDB que extraia do Postgres anexado apenas o que mudou desde a última marca d'água, com sobreposição de cinco minutos, aplicação idempotente e registro em tabela de controle."
"Aponte, neste pipeline, o que se perde quando a origem apaga uma linha, o que acontece se a execução falhar depois de gravar metade e o que quebra se a mesma janela rodar duas vezes."
Confira a contagem em cada etapa e explique cada diferença antes de seguir.
Verifique se o SQL gerado avança a marca d'água antes ou depois da gravação.
Registre o prompt junto do SQL, uma vez que ele integra o registro da decisão.
Segunda hora · Medição
Cada linha é um número obtido por execução, e não uma afirmação sobre o comportamento esperado do pipeline.
| Evidência | Como obter | O que ela demonstra |
|---|---|---|
| Custo de cada estratégia | Tempo e linhas lidas do full load contra o incremental | Quanto a janela economiza em leitura da origem |
| Divergência acumulada | Anti-junção entre destino e origem após as mutações | Que a perda é silenciosa e cumulativa |
| Efeito no negócio | Soma de receita no destino contra a soma na origem | Que a divergência técnica altera o número apresentado |
| Idempotência | Contagem antes e depois do replay da mesma janela | Que a reentrega não duplica o dado |
| Auditoria | Linhas em ctl.extracao ao final do encontro | Que cada execução é rastreável e reproduzível |
Ponte com a Aula 1 · Spec-Driven Development
A decisão de extração entra no projeto como requisito, decisão registrada e critério verificável.
Ingerir todas as alterações de pedidos da origem, inclusive exclusões e correções retroativas.
Atraso da marca d'água menor ou igual a uma hora; taxa de rejeição até 0,1%; qualquer janela dos últimos 30 dias reprocessável sem intervenção manual.
Captura pelo log de transações em vez de incremental por campo de atualização. Contexto: a origem apaga registros e corrige lançamentos com data retroativa. Consequência: exige retenção do log e garantia de ordenação.
Dado que o lote de 09/09/2026 já foi carregado, quando reprocesso o mesmo identificador de lote, então o volume no destino permanece igual e a auditoria registra duas execuções.
Entrega do card de trabalho
O que o grupo entrega ao final da segunda hora, e o que será conferido.
O SQL da carga inicial, da janela incremental e da reconciliação; os três números medidos; e uma frase por número que declare o efeito sobre a decisão de negócio do parceiro.
A origem transacional está no ar e a contagem inicial coincide com a do CSV.
A tabela de controle registra cada execução com lote, janela, marca d'água e status.
A marca d'água avança somente após a gravação do lote concluir.
Os três casos de mutação foram aplicados e a divergência resultante está medida.
O replay da mesma janela mantém a contagem e registra duas execuções distintas.
A decisão sobre exclusão marcada ou removida está declarada por escrito.
Autoestudos · antes do próximo encontro
O que a origem precisa garantir para que a extração seja correta, e o que fazer quando ela não garante?
Leia a visão geral identificando o que a captura pelo log exige da origem, e compare com o que a origem do seu parceiro oferece hoje.
debezium.io · documentação LeituraObserve como o capítulo trata recusa de carga e recuo exponencial, e traduza as recomendações para a extração de uma API com limite de requisições.
sre.google · capítulo DocumentaçãoPercorra a documentação da extensão usada no laboratório, com atenção ao que é lido sob demanda e ao que é materializado no motor.
duckdb.org · documentaçãoAula 12 · Síntese
Coleta e Extração · 09/09/2026 · Prof. Hermano
Levantar o contrato de uma fonte, escolher entre full load, incremental por carimbo de tempo e captura pelo log a partir da semântica de atualização da origem, e construir uma extração idempotente cuja divergência seja medida e explicada.
Primeira hora de exposição dialogada em três blocos, cada um encerrado por checklist de aplicação e erro comum. Segunda hora de atividade em grupo: os estudantes montam uma origem transacional em Postgres com os pedidos da Olist, extraem por full load e por janela incremental para o lakehouse da Aula 10, aplicam mutações deliberadas de atualização e exclusão na origem e medem exatamente o que cada estratégia deixou de capturar.