continuous learning company
Voltar para publicações
Necy Vieira
Necy Vieira Conheça o autor

Streaming em três partes: origem, transformação e destino

Entenda readStream, DataFrames e writeStream. Acompanhe pedidos do Kafka até uma tabela Silver em Delta Lake e veja como o checkpoint participa da recuperação.

19/10/2026 Engenharia de Dados
Infográfico Streaming em três partes: origem Kafka com readStream, transformação por DataFrames e SQL, destino Delta Lake com writeStream e checkpoint durável

Uma pergunta simples para cada responsabilidade

Uma loja recebe pedidos continuamente. Para transformar essas mensagens em dados utilizáveis, separe três perguntas: de onde os eventos vêm, o que precisa mudar e onde o resultado será gravado? Essa separação ajuda a explicar o pipeline e a localizar problemas sem misturar leitura, regras de negócio e armazenamento.

Este conteúdo aprofunda a divisão de responsabilidades. Para uma visão mais ampla do motor, veja Spark Structured Streaming; para a organização das tabelas em camadas, consulte Lakehouse com Delta. Aqui o foco é ligar origem, transformação e destino em um exemplo de pedidos.

1. Source — Origem

Kafka + readStream: leia eventos e metadados.

2. Transformation

DataFrames ou SQL: interprete e valide.

3. Sink — Destino

writeStream + Delta: grave os pedidos válidos.

1. Source: leia eventos e reconheça sua posição

Kafka organiza eventos em tópicos divididos em partições. O offset identifica uma posição dentro de uma partição; não é um número global do tópico. Duas partições podem ter o mesmo offset. Para rastrear um registro, mantenha tópico, partição e offset juntos.[1][2]

No Spark, readStream.format("kafka") configura a entrada. A mensagem chega em value como bytes; converter para texto não valida o JSON nem aplica o contrato da loja. A opção startingOffsets define a posição inicial de uma consulta nova. Ao retomar um checkpoint válido, o progresso salvo é que orienta a continuação.[2]

2. Transformation: dê significado e qualidade aos campos

DataFrames e SQL descrevem as transformações: interpretar o JSON, selecionar colunas, converter tipos e aplicar regras. Neste exemplo, o contrato espera identificador, valor decimal e horário do evento. A função from_json interpreta a mensagem com um esquema explícito; mensagens ou campos inválidos precisam de tratamento.[3][4]

A loja aceita apenas identificador preenchido, valor maior que zero e horário interpretável. Um número negativo pode ser um decimal perfeitamente válido e, mesmo assim, violar a regra do pedido. Por isso, tipagem e validação de negócio são verificações diferentes. Planeje preservar a entrada e investigar rejeitados; filtrar não é corrigir o dado.

3. Sink: materialize os resultados

O destino é configurado com writeStream. Aqui usamos Delta Lake, modo append e uma tabela de pedidos válidos chamada Silver. A transformação é sem agregação: cada pedido aprovado mantém seu nível de detalhe. Uma tabela Silver é uma decisão de organização da arquitetura, não um modo especial de escrita do Spark.[3][5]

Descrever a leitura e as transformações ainda não inicia a consulta. O método start cria a execução em streaming. O exemplo permanece ativo para acompanhar novas mensagens; awaitTermination mantém o programa aguardando seu término.[3]

Checkpoint: progresso durável, não uma quarta camada de dados

O checkpoint registra o progresso e os commits dos micro-lotes. Quando existem operações com estado, como agregações, participa também da recuperação desse estado. O exemplo de filtro não mantém uma soma entre lotes. Use um diretório durável e exclusivo por consulta, separado do destino dos dados; não o compartilhe com outra execução independente.[3][6]

Na retomada, mantenha a identidade da consulta e o checkpoint compatível. Mudanças de fontes, destinos ou operações com estado podem impedir a reutilização. Não apague a pasta para tentar resolver uma falha sem planejar o reprocessamento.[6]

A recuperação depende também da origem e do destino: os eventos necessários precisam continuar disponíveis no Kafka, e o destino deve suportar as garantias pretendidas. Delta oferece integração transacional com streaming, mas isso não remove duplicidades de negócio publicadas como novos eventos. Evite prometer processamento exatamente uma vez para qualquer combinação de componentes.[2][3][5]

Exemplo prático: pedido JSON até a Silver

O código abaixo é um modelo para executar no seu ambiente, não um cluster executado por este site. É necessário ter Spark com conectores Kafka e Delta compatíveis, acesso ao broker, tópico de teste e armazenamento durável. Configure autenticação e permissões pelo mecanismo seguro do ambiente; não coloque credenciais no código publicado. Substitua broker e caminhos antes de executar.

Passo A — Configure a origem

from pyspark.sql import functions as F
from pyspark.sql.types import (
    StructType, StructField, StringType,
    DecimalType, TimestampType,
)

# A sessão spark já precisa de Kafka e Delta configurados.
spark.conf.set("spark.sql.session.timeZone", "UTC")
broker = "SEU_BROKER:9092"
destino = "/dados/demo_streaming/silver/pedidos"
checkpoint = "/dados/checkpoints/demo_streaming/pedidos_silver"

# 1. ORIGEM: use um tópico exclusivo de teste.
entrada = (
    spark.readStream.format("kafka")
    .option("kafka.bootstrap.servers", broker)
    .option("subscribe", "pedidos")
    .option("startingOffsets", "earliest")
    .load()
    .select(
        F.col("value").cast("string").alias("payload"),
        "topic", "partition", "offset",
    )
)

Em uma consulta nova, earliest considera os eventos ainda retidos, não recupera mensagens já removidas do Kafka. Na retomada, não use essa opção como substituta do checkpoint.[2]

Passo B — Interprete e valide

# 2. TRANSFORMAÇÃO: contrato e regras do pedido.
schema = StructType([
    StructField("pedido_id", StringType()),
    StructField("valor", DecimalType(12, 2)),
    StructField("event_time", TimestampType()),
])

interpretados = entrada.select(
    "payload", "topic", "partition", "offset",
    F.from_json("payload", schema).alias("pedido"),
).select("payload", "topic", "partition", "offset", "pedido.*")

validos = interpretados.filter(
    F.col("pedido_id").isNotNull()
    & (F.length(F.trim(F.col("pedido_id"))) > 0)
    & F.col("valor").isNotNull()
    & (F.col("valor") > 0)
    & F.col("event_time").isNotNull()
)

Passo C — Inicie a escrita em Delta

# 3. DESTINO: checkpoint exclusivo desta consulta.
consulta = (
    validos.writeStream.format("delta")
    .outputMode("append")
    .option("checkpointLocation", checkpoint)
    .queryName("pedidos_silver_demo")
    .start(destino)
)

consulta.awaitTermination()

O programa aguarda no último comando. Em notebook, monitore e pare a consulta de forma controlada em outra célula, por exemplo com consulta.stop(). Reutilizar o mesmo checkpoint compatível permite retomar; este exemplo não implementa deduplicação, atualizações de pedidos nem saída de quarentena.[3][6]

Laboratório guiado: acompanhe quatro mensagens

Publique em um tópico isolado os três objetos abaixo e uma mensagem com o texto json-invalido. Este laboratório é guiado: o navegador não se conecta ao Kafka.

{"pedido_id": "P001", "valor": 99.9, "event_time": "2026-10-19T10:00:00Z"}
{"pedido_id": "P002", "valor": -10.0, "event_time": "2026-10-19T10:00:01Z"}
{"pedido_id": "P003", "valor": 40.1, "event_time": "2026-10-19T10:00:02Z"}
json-invalido

Resultado esperado pelas regras: P001 e P003 seguem para a Silver. P002 é rejeitado pelo valor negativo; a mensagem inválida não produz os campos obrigatórios. São dois registros aprovados, sem agregação. Isso é uma expectativa derivada da amostra, não uma saída observada de um cluster.

Confirme as linhas no destino em outra sessão com suporte Delta. Depois, interrompa e reinicie a mesma consulta com o checkpoint preservado, publique um novo pedido e observe o progresso. Registre falhas e rejeições. Não apague o checkpoint nem reutilize o diretório em outra consulta durante o teste.

Conclusão

Separar responsabilidades facilita a manutenção: Source explica a leitura e a posição dos eventos; Transformation define o significado e a qualidade; Sink materializa o resultado. O checkpoint sustenta a retomada da consulta, em conjunto com as condições da origem e do destino. Pratique a identificação desses papéis no jogo abaixo e revise os conceitos no quiz.

Continue sua trilha

Trilha de Engenharia de Dados · 0% concluído · 0 de 24 conteúdos concluídos

Jogo: quem resolve esta missão?

Leia o desafio e escolha a responsabilidade correta. Você pode tentar novamente após um erro. A pontuação considera os acertos na primeira tentativa. Não há cronômetro.

Quiz: revise as três responsabilidades

Responda às seis questões e confira as explicações.

1. Qual é a responsabilidade da origem?

2. O que um offset identifica no Kafka?

3. Qual operação pertence à transformação?

4. Qual configuração corresponde ao destino deste exemplo?

5. Qual é o uso correto do checkpoint?

6. O que esperamos das quatro mensagens do laboratório?

Referências oficiais

Documentação consultada em 19/10/2026. Confira a compatibilidade de Spark, Kafka e Delta no seu ambiente.

  1. Apache Kafka — introdução e partições
  2. Apache Spark — integração Structured Streaming e Kafka
  3. Apache Spark — APIs e recuperação de Structured Streaming
  4. PySpark 4.0.1 — from_json e esquema explícito
  5. Delta Lake — tabelas como destino de streaming
  6. Databricks — checkpoints exclusivos e reinício