Ingestão na AWS: Auto Loader, File Events, Kafka/MSK e Sinks Idempotentes

Tudo o que vem depois neste curso, as transações Delta da lição 04, os pipelines declarativos da lição 07, os gates de qualidade da lição 10, pressupõe uma tabela bronze que já está sendo preenchida corretamente. A ingestão é onde os projetos de lakehouse falham em silêncio: um checkpoint descartado "para corrigir o lag", um diretório de schema estacionado dentro do prefixo de chegada para que a stream descubra os próprios arquivos de estado, uma query Kafka deixada no startingOffsets padrão, fazendo a primeira execução pular três horas de backlog, ou uma stream de listagem de diretório com trigger de um segundo cuja conta de LIST cresce a cada hora de uptime.

A mecânica não é complicada. A recomendação da própria Databricks cabe em uma frase: "a Databricks também recomenda o Auto Loader sempre que você usar Apache Spark Structured Streaming para ingerir dados de armazenamento de objetos em nuvem" (docs.../auto-loader, última atualização em 2026-09-11). O que é complicado é a higiene: onde o estado vive, o que acontece quando uma coluna aparece, qual modo de descoberta se paga, e como um micro-batch reprocessado evita escrever linhas duas vezes. Essa é esta lição.

Todo fato abaixo vem da documentação da Databricks na AWS (páginas de Auto Loader, directory-listing, file-notification, schema, production, clean-source, best-practices, FAQ, checkpoints, output-mode, triggers, foreach, Delta streaming, Kafka e JDBC), da documentação do Apache Spark e da AWS, e de blogs de engenharia da Databricks com data: todos acessados ou datados de outubro de 2026. O escopo da plataforma é Databricks na AWS: Azure Event Hubs não existe nesse substrato e está fora do escopo aqui.

Nesta lição você vai:

• escrever o próprio notebook bronze de Auto Loader, cloudFiles.format, schemaLocation, checkpointLocation, useManagedFileEvents, inferColumnTypes, schemaEvolutionMode, mergeSchema no sink Delta, e comentar cada padrão;
• colocar o local de schema e o checkpoint onde eles não possam ser descobertos, expirados ou compartilhados, e defender a escolha contra o instinto de "pôr o estado ao lado dos dados";
• calcular as três contas de LIST para um prefixo de chegada sob três políticas de trigger, e escolher entre listagem de diretório, notificações clássicas de arquivo SNS+SQS e file events gerenciados com suas permissões, limites e comportamento de backfill;
• rodar um esboço de throughput para um pico de 1,8 milhões de arquivos: taxa de chegada contra taxa de serviço, o teto duro de arquivos contra o teto suave de bytes, e o que acontece quando alguém "com cuidado" demais define maxFilesPerTrigger baixo demais;
• configurar Amazon MSK com AWS_MSK_IAM, incluindo os nomes de classe shaded e a porta que precisa bater com o modo de autenticação, mais a aritmética de dimensionamento de maxOffsetsPerTrigger;
• escolher um modo de saída contra a matriz de suporte do Delta, tornar foreachBatch idempotente com txnAppId/txnVersion, e defender a cadeia end-to-end de exactly-once;
• unificar batch e streaming em um único caminho de código com Trigger.AvailableNow, e precificar o job bronze noturno em DBUs em outubro de 2026;
• estudar dois casos nomeados de clientes da AWS (Asurion e Burberry), ler a caixa de atualizações de 2026, e praticar com 13 questões no estilo de exame mais quatro verificações interativas.

---

1. Ingestão na lakehouse da AWS: três famílias de origem, um caminho de escrita

A ingestão Databricks-on-AWS tem três famílias que importam em produção, mais uma de brinquedo:

Três coisas nessa tabela são estruturais. Primeiro, todas quatro convergem para o mesmo caminho de escrita: writeStream → checkpointLocation → modo de saída → Delta. O código de transformação é idêntico para spark.read e spark.readStream porque ambos retornam DataFrames, essa é a história de unificação batch/streaming da seção 9. Segundo, JDBC não tem nenhuma fonte de streaming documentada pela Databricks: a documentação atual descreve leituras em batch, conexões UC governadas e foreachBatch para escritas; DML em nível de linha no banco de origem é explicitamente não suportado ("The Spark JDBC data source does not support arbitrary DML statements", docs.../connect/jdbc-connection, acesso em 2026-10). Terceiro, o checkpoint é a query, apague-o e você recomeça do zero: para Kafka isso significa que startingOffsets se aplica de novo; para Auto Loader, o estado de arquivos descobertos desapareceu.

• 📚 Você sabia? O Auto Loader não é novo. A Databricks o anunciou em 2020-02-24 como "uma fonte otimizada de arquivos em nuvem para o Apache Spark, que carrega dados de forma contínua e eficiente do armazenamento em nuvem à medida que novos dados chegam", citando Fivetran, Qlik, Infoworks, StreamSets e Syncsort como ferramentas de ingestão parceiras no lançamento (databricks.com/blog/2020/02/24/introducing-databricks-ingest-easy-data-ingestion-into-delta-lake.html, 2020-02-24). O problema que ele resolveu nunca mudou: "tanto o custo quanto a latência podem somar muito rápido à medida que mais e mais arquivos entram em um diretório por causa da listagem repetida de arquivos". As cifras de escala que você verá citadas, "bilhões de arquivos" para backfills e "milhões de arquivos por hora" para ingest quase em tempo real, são afirmações de capacidade do fornecedor da página de docs (2026-09-11), não benchmarks de clientes: trate-as como folga de projeto, nunca como SLA.

---

2. Anatomia do Auto Loader: a fonte cloudFiles

2.1 As opções que importam (out 2026)

spark.readStream.format("cloudFiles") é uma fonte comum de Structured Streaming. O que a torna Auto Loader é o motor de descoberta: conforme arquivos são encontrados, seus metadados são persistidos "em um store chave-valor escalável (RocksDB) no checkpoint location", o que "garante que os dados sejam processados exactly once" (docs .../auto-loader, 2026-09-11).

Dois padrões surpreendem todo mundo. includeExistingFiles=true significa que a primeira subida de um checkpoint novo varre o prefixo inteiro (esse é o seu backfill). E maxFilesPerTrigger=1000 é um limite duro, enquanto o limite de bytes é suave: "Um arquivo individual nunca é dividido entre micro-batches" (docs.../spark/api-options, data da página 2026-10-05).

2.2 Exemplo resolvido E1: um notebook bronze de Auto Loader com forma de produção

O que os números significam enquanto ele roda: a primeira execução amostra os primeiros 50 GB ou 1,000 arquivos (o que for cruzado primeiro, mais recente por hora de modificação) para inferir o schema; cada micro-batch seguinte é limitado a 1,000 arquivos, a menos que o runtime faça o auto-tune (DBR 18.0+); Trigger.AvailableNow processa apenas arquivos que chegaram antes do horário de início da query e se desliga sozinho; e se uma coluna nova aparecer, a query para com UnknownFieldException depois de _schemas já ter sido atualizado, então é o job, não uma pessoa, que a reinicia (seção 3).

---

3. Inferência, evolução de schema e rescue

3.1 O que a inferência de fato amostra

Na primeira definição do DataFrame, o Auto Loader "lista o seu diretório de origem e escolhe os 50 GB mais recentes (por hora de modificação do arquivo) ou 1000 arquivos, e usa esses para inferir o schema dos seus dados" (FAQ do Auto Loader, datado de 2026-06-23). O resultado é gravado em um diretório _schemas sob cloudFiles.schemaLocation, e é esse o histórico de schema que a stream recarrega em cada reinício: "Quando a stream reinicia, ela pega o schema evoluído do local de schema e começa a executar sem nenhum overhead de inferência" (mesmo FAQ).

Padrões que mordem:

• JSON, CSV e XML inferem todas as colunas como strings a menos que você defina cloudFiles.inferColumnTypes=true. Formatos tipados (Parquet, Avro) fazem merge dos tipos codificados no lugar.
• Se o diretório de origem estiver vazio, você precisa fornecer um schema: não há nada para amostrar.
• cloudFiles.schemaHints deixa você fixar tipos conhecidos ("order_id=STRING, amount=DECIMAL(12,2)") sem escrever o schema inteiro à mão.
• Colunas de partição são inferidas a partir de caminhos estilo Hive, mas colunas de partição novas não são evoluídas: declare-as com cloudFiles.partitionColumns.
• Overrides existem: spark.databricks.cloudFiles.schemaInference.sampleSize.numBytes (por exemplo 10gb) e ...sampleSize.numFiles.

3.2 Modos de evolução e o loop de reinício

A sequência em uma mudança de schema é fixa, e vale memorizar, porque é um design de alerta-e-replay e não uma correção silenciosa:

Dois fatos de apoio. O lado de escrita precisa concordar: .option("mergeSchema", "true") no sink Delta, ou a tabela se recusa a mudança aditiva. E um rename é tratado como um add, o nome novo vira uma coluna, enquanto a antiga é preenchida com NULL nas linhas novas (docs.../data-engineering/schema-evolution, acesso em 2026-10). O schema de uma query de streaming fica "travado durante a fase de planejamento", então qualquer mudança de origem em pleno voo falha a query e exige reinício; é por isso que a documentação recomenda rodar streams de Auto Loader como jobs do Lakeflow/Workflows em vez de notebooks all-purpose rodando para sempre.

3.3 Exemplo resolvido E2: uma stream de eventos que nunca falha, com tipos fixados

_rescued_data guarda o que o schema não conseguiu aceitar, "coluna ausente do schema / tipo não confere / caixa não confere", como um blob JSON ao lado do caminho do arquivo de origem, e é assim que você mantém uma faixa sem perda de dados e um sinal de qualidade mensurável ao mesmo tempo. Use rescue para faixas que nunca podem parar (clickstream, IoT); use addNewColumns mais um job com reinício automático para faixas em que uma coluna nova é um evento que você quer perceber.

3.4 ⚠️ ALERTA: nunca coloque estado de schema ou checkpoint no caminho dos dados

⚠️ ALERTA: cloudFiles.schemaLocation e checkpointLocation nunca podem ficar dentro do diretório de chegada da origem, e nenhum dos dois pode ficar sob uma política de ciclo de vida de objetos de nuvem.

1. Estar dentro do caminho dos dados significa autodescoberta. Se _schemas/ ou o checkpoint ficar sob s3://acme-landing/raw/orders/, o Auto Loader eventualmente vai listar os próprios arquivos de estado como entradas. Mantenha o estado em um prefixo diferente ou em um volume do Unity Catalog (/Volumes/<catalog>/<schema>/checkpoints/...), nunca sob o diretório de dados da tabela.
2. Uma regra de ciclo de vida que expira o estado destrói a query. "A Databricks recomenda definir o local do checkpoint em um local sem uma política de ciclo de vida de objetos de nuvem. Se os arquivos no local do checkpoint forem limpos conforme a política, o estado da stream é corrompido. Se isso acontecer, você precisa reiniciar a stream do zero" (docs .../auto-loader/production, rodapé 2026-09-18). A mesma frase vale para schemaLocation.
3. Separe por workload. Cada workload de ingestão do Auto Loader exige um checkpoint de streaming próprio. Dois workloads dividindo um checkpoint, ou um único diretório _schemas, vão brigar pelo estado.
4. Estado ao lado de uma tabela Delta precisa de prefixo de sublinhado. Se você precisar colocar um checkpoint junto com uma tabela, use /_checkpoints: o VACUUM "ignora quaisquer diretórios que começam com _" (docs .../structured-streaming/delta-lake, datada de 2026-08-24), então a manutenção não vai comê-lo.
5. Igualdade pode, contenção não. A documentação permite explicitamente schemaLocation == checkpointLocation; o que ela nunca permite é estado dentro do caminho de entrada ou sob expiração.

---

4. Detecção de arquivos: listagem de diretório versus notificações de arquivo

O Auto Loader "suporta dois modos de detecção de arquivos. Por padrão, o Auto Loader usa o modo de listagem de diretório. No entanto, a Databricks recomenda o modo de notificação de arquivo usando file events para a maioria dos workloads" (docs .../auto-loader, 2026-09-11). Escolher entre eles é a decisão de custo e de infraestrutura desta lição.

4.1 Listagem de diretório (padrão)

Cada trigger lista a árvore de entrada. Duas propriedades tornam isso viável: o Auto Loader "usa APIs nativas da nuvem para obter listas de arquivos", e no S3 cada LIST devolve até 1,000 chaves, então o número de chamadas de API escala como arquivos ÷ 1,000 e não como diretórios × triggers. Essa é a diferença em relação ao file source do OSS Spark, cujo custo a documentação modela como "1 (diretório base) + 365 (por dia) × 24 (por hora) = 8761 chamadas" para um layout YYYY/MM/DD/HH (docs .../auto-loader/directory-listing-mode, 2026-09-11).

O aviso documentado é sobre frequência: com triggers contínuos como Trigger.ProcessingTime, o modo de listagem de diretório "lista continuamente o diretório inteiro e pode aumentar significativamente os custos da API LIST". Três regras de higiene:

• mantenha nomenclatura lexical de arquivos (YYYY/MM/DD/HH, com zeros à esquerda: os arquivos de CDC do AWS DMS como LOAD00000001.csv e os nomes de objeto do Kinesis Firehose são os exemplos da própria documentação), ainda que o Auto Loader não garanta a ordem em que arquivos são descobertos ou processados;
• prefira Trigger.AvailableNow a um trigger contínuo nesse modo;
• a listagem incremental está deprecada: em modo auto, uma listagem completa de diretório roda depois de 7 listagens incrementais consecutivas (ajustável com cloudFiles.backfillInterval), e o DBR 11.3 LTS+ deixa você mudar o caminho de entrada sem um checkpoint novo: capacidade não suportada para notificações de arquivo.

4.2 Notificações clássicas de arquivo: SNS + SQS

Nesse modo o Auto Loader liga a notificação de bucket do S3 (ObjectCreated) por meio de um tópico AWS SNS para uma fila AWS SQS (prefixo de recurso databricks-auto-ingest) e depois consome a fila. A política de setup precisa do conjunto de ações documentado, s3:GetBucketNotification, s3:PutBucketNotification, sns:CreateTopic, sns:Subscribe, sns:Publish, sqs:CreateQueue, sqs:ReceiveMessage, sqs:DeleteMessage, sqs:SendMessage, sqs:SetQueueAttributes, sqs:ChangeMessageVisibility, sqs:PurgeQueue em databricks-auto-ingest-*, e depois do setup a stream em execução só precisa da política reduzida de consumo (docs.../auto-loader/file-notification-mode, rodapé 2026-10-07). A mesma página limita o padrão a 100 por bucket S3.

Dois avisos vêm junto. A entrega de eventos é best-effort, "provedores de nuvem não garantem 100% de entrega de todos os arquivos de evento", então SLAs de completude no modo clássico são comprados com relistas assíncronas via cloudFiles.backfillInterval que ingerem apenas os arquivos perdidos (sem duplicatas, porque o checkpoint já sabe o que viu). E você não consegue mudar o caminho de entrada sem um checkpoint novo nesse modo.

4.3 File events gerenciados (recomendado)

A forma moderna é habilitada na external location, não por stream: uma única fila de notificação de arquivos para todas as streams que processam arquivos de uma dada external location, ativada com cloudFiles.useManagedFileEvents=true. Requisitos: um workspace habilitado para Unity Catalog, permissão para criar uma storage credential e uma external location, e Databricks Runtime 14.3 LTS ou superior (mesma página, 2026-10-07).

O que você ganha: menos grants de IAM (permissão de nuvem única, e depois nenhuma fila por stream), tuning e limpeza automáticos, backfill automático, "a Databricks faz backfill automático dessas external locations com uma listagem completa quando os file events são habilitados pela primeira vez, e depois continua fazendo backfill a cada aproximadamente 24 horas", e a instrução explícita de não definir um intervalo de backfill nesse modo. O que você precisa respeitar: "O serviço de file events otimiza a descoberta de arquivos fazendo cache dos arquivos criados mais recentemente. Se o Auto Loader rodar com pouca frequência, esse cache pode expirar … invoque o Auto Loader pelo menos uma vez a cada sete dias." Um job noturno ou horário de AvailableNow passa desse piso com folga; uma execução manual trimestral, não.

Trocar de modo é seguro: "você pode alternar entre notificações de arquivo e listagem de diretório a qualquer momento e ainda manter as garantias de processamento exactly-once" (mesma página).

4.4 Exemplo resolvido E3: a conta de LIST, calculada de três formas

Entradas (todas oficiais): o S3 devolve 1,000 chaves por LIST; "Requisições LIST para qualquer storage class são cobradas na mesma taxa que as requisições PUT, COPY e POST do S3 Standard": $0.005 por 1,000 em us-east-1, enquanto DELETE e CANCEL são grátis (aws.amazon.com/s3/pricing, acesso em 2026-10). Prefixo de chegada: 2,000,000 arquivos. A aritmética abaixo é nossa; as entradas são da AWS.

Leia a forma, não só os dólares: o mesmo prefixo de 2M de arquivos custa 900× mais com um trigger de 1 segundo do que com um AvailableNow de 15 minutos, porque o multiplicador é a frequência de listagem: não o volume de dados. File events gerenciados substituem a listagem por trigger por chamadas de API de fila, restando apenas a listagem automática de backfill de ~24 horas. Nós deliberadamente não precificamos o lado do SQS/SNS aqui: as fontes desta lição não trazem nenhum preço verificado de fila da AWS, então confira você mesmo aws.amazon.com/pricing antes de modelar isso.

• 📚 Você sabia? O LIST é cobrado como escrita, não como leitura: "Requisições LIST para qualquer storage class são cobradas na mesma taxa que as requisições PUT, COPY e POST do S3 Standard": $0.005 por 1,000: enquanto DELETE e CANCEL são grátis (aws.amazon.com/s3/pricing, acesso em 2026-10). E não existe rename de propósito geral no S3: "S3 Express One Zone é o único storage class que suporta a API RenameObject", então um arquivo de estilo MOVE é um par copy + delete cobrado pelas taxas de PUT/COPY/LIST, e, em termos de notificação clássica, essa cópia aparece como mais um evento ObjectCreated. Essa é uma segunda razão para os file events gerenciados, que não disparam de novo nas suas próprias cópias de bookkeeping, serem o modo recomendado.

---

5. Throughput e higiene de produção

5.1 Exemplo resolvido E4: um esboço de throughput para um pico de 1,8 milhões de arquivos

Cenário: um parceiro despeja 1,800,000 arquivos JSON de 120 KB no prefixo de chegada durante uma janela noturna de duas horas (216 GB), e depois mantém um filete chegando. Taxa de chegada = 1,800,000 ÷ 7,200 s = 250 arquivos/s.

Dimensionando os micro-batches:

• Padrão maxFilesPerTrigger=1000 → cada micro-batch carrega 1,000 arquivos = 120 MB.
• Defina maxBytesPerTrigger="500mb" no lugar e esse teto de bytes suave permitiria 500 MB ÷ 120 KB ≈ 4,166 arquivos, mas o limite de arquivos é um limite duro, então o batch efetivo continua em 1,000 arquivos. Vale o limite que for atingido primeiro.
• Suponha que o cluster sustente 1,0 s por micro-batch → taxa de serviço 1,000 arquivos/s (120 MB/s). Utilização ρ = 250 ÷ 1,000 = 0.625: a fila esvazia.
• Um backlog de 1.8M de arquivos esvazia a 1,000 − 250 = 750 arquivos/s líquidos → 2,400 s = 40 minutos, tendo processado 2.4M de arquivos no total (≈288 GB).

Agora o modo de falha que um engenheiro "cuidadoso" cria: definir maxFilesPerTrigger=100 "para ser gentil com o cluster" limita o serviço a 100 arquivos/s < 250 arquivos/s de chegada, a fila cresce a 150 arquivos/s sem limite, e nenhum tamanho de cluster conserta um knob ruim de controle de admissão. No DBR 18.0+, tanto cloudFiles.maxFilesPerTrigger quanto cloudFiles.maxBytesPerTrigger são "configurados dinamicamente e não precisam ser definidos manualmente" (docs.../spark/api-options, 2026-10-05); fixá-los ali briga com o tuning automático. E se o pico for genuinamente enorme e de uma vez só, rode Trigger.AvailableNow como uma task do Workflows em vez de um trigger contínuo, ele limita a taxa entre micro-batches e se desliga quando se atualiza.

5.2 Retenção: maxFileAge, cleanSource, backfill

A economia do cleanSource é o mesmo argumento da seção 4: "Arquive os arquivos processados com cloudFiles.cleanSource … Isso reduz tanto os custos de armazenamento quanto os de listagem de diretório para streams de longa duração": você para de pagar para relistar arquivos que nunca mais vai ler.

5.3 Monitorando a origem

Três métricas te dizem se a ingestão está saudável antes que os alertas de frescor a jusante disparem: numFilesOutstanding, numBytesOutstanding e (notificações de arquivo) approximateQueueSize: mais a tabela de estado:

Um numFilesOutstanding crescente com taxa de processamento estável significa que você está dimensionado abaixo do necessário (conserte os limites de taxa, não o checkpoint); um approximateQueueSize travado no modo clássico de notificação significa que o consumidor não consegue esvaziar a fila: permissões, ou o teto de 100 por bucket.

---

6. Kafka e Amazon MSK como origem

6.1 As opções que importam

Leitura mínima: spark.readStream.format("kafka").option("kafka.bootstrap.servers", "<server:9094>").option("subscribe", "orders").option("startingOffsets", "latest").load(), e então as quatro opções que decidem se o seu primeiro dia vai bem:

O schema de linha é um fixo de sete colunas: key binary, value binary, topic string, partition int, offset long, timestamp timestamp, timestampType int. Autenticação na AWS é SSL ou SASL_SSL com PLAIN/SCRAM/AWS_MSK_IAM: ou, no caminho governado, uma service credential / conexão do Unity Catalog, caso em que você não deve definir kafka.security.protocol nem sasl.* você mesmo. Se você de fato dirigir o cliente diretamente: sempre prefixe as propriedades do cliente com kafka. e use sempre os nomes de classe shaded da Databricks (kafkashaded., shadedmskiam.), ou você vai encontrar SaslException / RESTRICTED_STREAMING_OPTION_PERMISSION_ENFORCED.

6.2 Exemplo resolvido E5: leitura MSK IAM com limitação de taxa

Aritmética de dimensionamento (nossa, sobre semântica oficial): a chegada no pico é de 12,000 msg/s em 6 partições com 400 bytes em média. Com processingTime="30 seconds" e maxOffsetsPerTrigger=300000, a capacidade é 300,000 ÷ 30 = 10,000 msg/s < 12,000 msg/s, o backlog cresce a 2,000 msg/s. Suba para 600,000 → 20,000 msg/s de capacidade, payload do micro-batch 600,000 × 400 B = 240 MB, ρ = 0.6, estável. Dois fatos de apoio para o runbook de operações: a IAM role precisa de kafka-cluster:Connect e kafka-cluster:ReadData, e a porta precisa bater com o modo (9092 PLAINTEXT, 9094 SASL/SSL, 9098 IAM), mais VPC peering ou PrivateLink entre a VPC do Databricks e a VPC do MSK (docs.../kafka/authentication, 2026-07-10).

6.3 JDBC e a rate source

JDBC é um pull em batch nesta plataforma: credenciais via dbutils.secrets.get(scope="jdbc", key="username") (nunca na URL), ou o caminho governado .option("databricks.connection", "prod_pg") com o JAR do driver em um Volume: a memória do driver é limitada a 400 MiB, e o externalOptionsAllowList padrão permite apenas seis opções de leitura. Como escritas em nível de linha na origem não são suportadas, o padrão de upsert é sempre pull → Delta com appends idempotentes:

A rate source (spark.readStream.format("rate"), rowsPerSecond padrão 1, mais rampUpTime e numPartitions) emite linhas sintéticas de timestamp + value e é "intended for testing and benchmarking": perfeita para verificar checkpoint, modo de saída e a fiação do sink Delta em dois minutos, antes que qualquer permissão de S3 ou MSK entre na jogada.

---

7. Sinks: modos de saída, idempotência e MERGE

7.1 Modos de saída e a matriz do Delta

"Delta Lake, que sustenta todas as tabelas gerenciadas pelo Unity Catalog, suporta os modos append e complete, mas não o modo update" (docs .../structured-streaming/output-mode, 2026-09-11). Note também "Joins only support the append output mode". Appends simples do Delta são exactly-once pelo log de transações: "The Delta Lake transaction log guarantees exactly-once processing, even when there are other streams or batch queries running concurrently against the table" (docs .../structured-streaming/delta-lake, 2026-08-24).

7.2 Exemplo resolvido E6: upserts idempotentes em foreachBatch

"Você precisa usar foreachBatch para operações de merge do Delta Lake no Structured Streaming", e foreachBatch() "provides only at-least-once write guarantees", então a idempotência é problema seu (docs.../structured-streaming/foreach, datada de 2026-08-24).

Para appends simples escritos a partir de foreachBatch, vincule a identidade do batch explicitamente: .option("txnAppId", app_id).option("txnVersion", batch_id), o Delta "uses txnAppId and txnVersion to identify and ignore duplicate writes". Três regras das mesmas páginas: se você apagar o checkpoint e reiniciar, precisa fornecer um txnAppId diferente, porque "New checkpoints start with a batch ID of 0"; não capture e tente de novo exceções localmente, deixe os erros propagarem para que o orquestrador reexecute o batch inteiro e as métricas continuem honestas; e prefira uma escrita de streaming por sink, já que múltiplos sinks dentro de foreachBatch serializam o seu paralelismo.

---

8. Exactly-once de ponta a ponta

A garantia é uma cadeia, e cada elo é um componente que você já conheceu:

O conteúdo do checkpoint é fixo: offsets (o que foi lido), commits (quais micro-batches chegaram ao sink: "enabling exactly-once semantics"), estado, e metadata (o ID único da query mais as configurações). Consequências que você deve recitar de cor:

• um checkpoint por query, em armazenamento durável, fora de qualquer política de ciclo de vida;

• apagá-lo ou movê-lo recomeça do zero: Kafka faz replay conforme startingOffsets, o Auto Loader relista (e reprocesa o prefixo se includeExistingFiles era true na primeira execução original), e as escritas do Delta fazem replay a menos que txnAppId mude;

• para alvos não-Delta (um banco OLTP, uma fila, uma API HTTP) você é dono da idempotência indexada em batchId: "Se o batchId permanecer o mesmo, o resultado da sua operação deve permanecer o mesmo";

• foreachBatch nunca roda em modo de continuous processing, e em serverless apenas Trigger.AvailableNow() e o deprecado Trigger.Once() são suportados.

• 📚 Você sabia? Um checkpoint guardado ao lado de uma tabela Delta só sobrevive à manutenção se você o nomear com sublinhado: o VACUUM "ignora quaisquer diretórios que começam com _", e é por isso que a sugestão da própria documentação é "uma estrutura de diretórios como /_checkpoints" (docs .../structured-streaming/delta-lake, 2026-08-24). É uma pequena convenção de nomenclatura entre o estado da sua stream e um comando rotineiro de manutenção.

---

9. Unificação de batch + streaming

Um caminho de código, dois triggers. O mesmo leitor bronze roda como um job incremental noturno ou como uma stream de baixa latência; só o trigger, o checkpoint e o cluster mudam.

Trigger.AvailableNow "processes all files that arrived before the query start time", que é exatamente a semântica que um batch agendado quer, e usuários de SQL ganham o mesmo via STREAM read_files(...), que por sua vez usa o Auto Loader para tabelas de streaming (docs .../read_files, 2026-08-03).

9.1 Exemplo resolvido E7: quanto custa o job bronze noturno

Uma execução AvailableNow por noite, 25 minutos por execução, 30 execuções/mês → 12.5 cluster-hours/mês em um job cluster de 4 nós (1 driver + 3 workers). Para emissão usamos o próprio nó ilustrativo da Databricks: "an instance type which runs at 3 DBU/hour … a four node jobs cluster would be charged at $2.40 ($0.2 × 3 × 4)" (blog de custos de best-practices, 2022-10-18) → 12 DBU/h. Taxas: Jobs Compute $0.15/DBU e All-Purpose $0.55/DBU (AWS, EUA, tabela Premium, em out 2026: fonte documental: o registro de fornecedor Databricks G-Cloud 15 capturado em 2026-09-25, corroborado por leituras independentes em 2026-10; sempre reconfira system.billing.list_prices na sua própria conta). Lado da AWS: m5.xlarge a $0.192/h (tabela de preços da EC2, lida em 2026-10) × 4 nós.

A versão all-purpose é 3.7× a linha de DBU, batendo com a própria regra de bolso da Databricks de que pipelines pertencem a job compute, e ela também cobra por tempo ocioso que você teria de administrar sozinho. Workers em spot cortam a coluna da AWS em até 90% (o driver fica on-demand, com aviso de evicção de dois minutos); a coluna de DBU não muda, porque spot altera o preço da instância, nunca a taxa de emissão.

• 📚 Você sabia? O velho aviso de que "o lag de listagem após escrita do S3 pode fazer o Auto Loader perder arquivos" é história: desde 2020-12-01 "todas as operações GET, PUT e LIST do S3 … agora são fortemente consistentes" (AWS News Blog, 2020-12-01), confirmado no user guide do S3 (acesso em 2026-10). O risco atual de perda é a entrega de eventos, provedores de nuvem "não garantem a entrega de 100% de todos os eventos de arquivo", e é para isso que existem cloudFiles.backfillInterval (modo clássico) e o backfill automático de ~24 horas (file events gerenciados). Se um tutorial de 2021 mandar você construir uma gambiarra de consistência eventual para o S3, você pode apagar aquele parágrafo.

---

10. As armadilhas: doze confusões que esta lição não vai deixar você manter

1. "startingOffsets=latest está bom: é o padrão." Em uma query nova, ele pula o backlog em silêncio; queries retomadas usam o checkpoint de qualquer jeito. Defina earliest na primeira execução e depois confie no checkpoint para sempre.
2. Apagar um checkpoint para consertar lag. Ele recomeça do zero: Kafka faz replay ou pula conforme startingOffsets, o Auto Loader relista, e o Delta faz replay a menos que txnAppId mude (checkpoints novos reiniciam no batch ID 0).
3. Estado no caminho dos dados ou sob uma regra de ciclo de vida. Schema/checkpoint dentro do prefixo de chegada → autodescoberta; expiração por ciclo de vida → "o estado da stream é corrompido".
4. "schemaLocation e checkpointLocation precisam sempre diferir." Errado: a documentação permite que sejam iguais. O que precisa diferir é estado versus dados, e um checkpoint por workload.
5. Delta + outputMode("update"). Não suportado; use MERGE em foreachBatch. Delta dá só append e complete.
6. Confiar em foreachBatch para exactly-once. Ele é at-least-once: vincule txnAppId/txnVersion, mantenha o MERGE idempotente e nunca engula exceções localmente.
7. Trigger contínuo + modo de listagem de diretório. A explosão de custo clássica: listar a árvore inteira a cada trigger. Troque para AvailableNow ou file events.
8. Fixar maxFilesPerTrigger no DBR 18.0+. Lá ele é configurado dinamicamente, e fixes manuais brigam com o tuning; em runtimes antigos o padrão de 1,000 arquivos pode ser grande coisa pequeno demais para um backfill de vários TB.
9. maxFileAge significa uma coisa só. O file source usa como filtro de descoberta de 7 dias; o Auto Loader usa como estado de rastreamento de eventos com mínimo de 14 dias e recomendação de 90 dias, e na primeira execução ele limita o quanto para trás você ingeri.
10. cleanSource com dois leitores. O segundo leitor não encontra nada. Além disso: um destino de MOVE dentro do caminho de origem causa reingestão infinita, e movimentações entre bucket dão erro.
11. Classes Kafka não shaded ou prefixo kafka. ausente. Use kafkashaded. / shadedmskiam., e quando uma service credential do UC governa a conexão, não defina kafka.security.protocol você mesmo.
12. "maxOffsetsPerTrigger reseta a cada reinício." Controles de admissão valem para queries novas; uma query retomada lê o seu checkpoint. Dimensione uma vez, de propósito, e observe o lag em vez de re-tunar depois de cada incidente.

Veredito Comparativo: listagem de diretório versus notificações de arquivo (em out 2026)

• Escolha file events gerenciados (uma fila por external location do Unity Catalog, cloudFiles.useManagedFileEvents=true, DBR 14.3 LTS+) para a maioria dos workloads de produção: essa é a recomendação expressa da Databricks: "a Databricks recomenda o modo de notificação de arquivo usando file events para a maioria dos workloads" (docs.../auto-loader/file-notification-mode, 2026-10-07). Você ganha descoberta orientada por eventos sem LIST a cada trigger (E3: $0.30/mês contra $28.80 to $25,920/mês no mesmo prefixo de 2M de arquivos), permissões únicas em vez de IAM por stream, backfills completos automáticos na habilitação e a cada ~24 horas, e o requisito duro de rodar a stream pelo menos uma vez a cada 7 dias para o cache de file events não expirar.
• Fique na listagem de diretório quando o prefixo é pequeno e de vida curta, quando o job é uma execução agendada de Trigger.AvailableNow (96 listagens/dia ≈ $28.80/mês com 2M de arquivos: um erro de arredondamento perto do compute), quando você não consegue conceder s3:GetBucketNotification / s3:PutBucketNotification mais direitos de SNS/SQS, ou quando você precisa mudar o caminho de entrada sem um checkpoint novo (uma capacidade exclusiva da listagem de diretório). Ela é o padrão justamente porque não precisa de nada além de acesso de leitura.
• Notificações de arquivo clássicas SNS+SQS são o meio legado: orientadas por eventos como os file events, mas com o conjunto de ações de IAM publicado, um prefixo de recurso para governar (databricks-auto-ingest-*), um teto duro de 100 pipelines por bucket S3, filas por stream para limpar, entrega best-effort que exige cloudFiles.backfillInterval, e nenhuma mobilidade de caminho de entrada. Projetos novos pertencem aos file events gerenciados; o modo clássico sobrevive em estates que antecedem as external locations do Unity Catalog.
• A resposta armadilha: "notificações de arquivo custam mais porque você paga SNS e SQS." A conta que você de fato consegue modelar, S3 LIST a $0.005 por 1,000, escala com a frequência de listagem, e as fontes desta lição não trazem nenhum preço verificado de SQS/SNS (então não modele um de memória). Decida sobre permissões, comportamento de backfill, a regra de cache de 7 dias e o teto de 100 por bucket; trate os centavos de requisição como secundários.

---

Casos Reais

📋 Caso A: Asurion (seguros e proteção de dispositivos, Cloud: AWS) Desafio. Um estate legado de 8,000 tabelas, 10,000 views e ~600 data marts, com mapeamentos de ETL por tabela e uma camada batch/speed duplicada que não conseguia absorver novas fontes de forma barata. Stack na AWS. Spark Structured Streaming, Auto Loader e foreachBatch em tabelas Delta, ingerindo "database CDC feeds, APIs and flat files to streams from Kinesis, Kafka, SNS and SQS", com Databricks SQL alimentando 600 data marts: um data lake de produção explicitamente "on AWS" (https://www.databricks.com/blog/2021/09/16/large-scale-etl-and-lakehouse-implementation-at-asurion.html, 2021-09-16). Resultado relatado. "The Asurion data lake executes 4,000+ streaming jobs and hosts over 4,000 tables in a production data lake on AWS" (https://www.databricks.com/blog/2021/05/10/aws-guide-to-data-ai-summit-featuring-disney-comcast-capital-one-and-mcdonalds.html, 2021-05-10). Do ponto de vista arquitetural: "an unified approach to data movement from traditional ETL to streaming data pipelines between Delta tables" (2021-09-16). Relação com esta lição. Seções 1, 6 e 7: com 4,000+ jobs de streaming, a arquitetura é um framework de ingestão parametrizado (um padrão Auto Loader / foreachBatch, muitos feeds), e a lista de fontes nativas da AWS (Kinesis, SNS, SQS) é exatamente a razão pela qual as escolhas de substrato das seções 4 e 6 importam. ⏳ Nota temporal: cifras de 2021 relatadas na época; reconfira qualquer afirmação de concorrência de workspace naquele blog contra a documentação atual antes de reutilizá-la.

📋 Caso B: Burberry (varejo de luxo, Cloud: AWS) Desafio. Lotes diários de clickstream chegando "anywhere between 2:00 and 7:00 PM GMT", e um data warehouse em nuvem que pré-agregava o detalhe necessário para o Customer 360. Stack na AWS. Databricks Data Intelligence Platform com Snowplow Behavioral Data Platform para Customer 360 em tempo real: a página da história carrega a própria tag Cloud: AWS da Databricks (https://www.databricks.com/customers/burberry, página sem data, acesso em 2026-10). Resultado relatado. "99% Reduction in latency for customer clickstream data · 52x Increase in cookie duration"; "we've broken free from daily data batches and formed an accurate real-time view of our customers' digital activity" (mesma URL, acesso em 2026-10; origem da história em 2023). Relação com esta lição. Seções 4 e 9: um SLA de latência em arquivos de evento é um requisito de negócio, atendido por descoberta orientada por eventos mais um trigger de baixa latência, e não por um cluster maior. O gargalo era a cadência de chegada de arquivos, não o compute. ⏳ Nota temporal: uma cifra de origem de 2023 ainda exibida em 2026; cite-a como o que a Burberry relatou na época.

---

Atualizações de 2026 (em outubro de 2026)

---

---

Perguntas de Prática (Practice Questions)