JSONL em pipelines ETL: Kafka, Airflow e data warehouses
Um guia prático para usar JSONL (JSON Lines) como formato de troca de dados em pipelines ETL modernos. Aprenda a produzir e consumir eventos JSONL no Kafka, orquestrar transformações de JSONL em DAGs do Airflow e carregar dados JSONL no Snowflake, no BigQuery e no Redshift.
Por que JSONL é o formato ideal para a troca de dados em ETL
Pipelines de extração, transformação e carga (ETL) transferem dados entre sistemas que raramente compartilham o mesmo schema. JSONL é especialmente adequado para essa tarefa porque cada linha é um documento JSON completo e independente. Não há cabeçalhos que possam se perder, delimitadores que precisem ser escapados nem registros com várias linhas que precisem ser reconstruídos após uma falha parcial. Cada linha pode ser validada, transformada e roteada de forma independente, exatamente o que sistemas distribuídos como Kafka e Airflow precisam.
Ao contrário do CSV, JSONL preserva estruturas aninhadas, arrays e valores tipados sem ambiguidade. Já em relação ao Parquet e ao Avro, JSONL tem a vantagem de ser legível por humanos e dispensar ferramentas especiais para inspecionar seu conteúdo. Essas características fazem do JSONL uma escolha natural para conectar as etapas de um pipeline: tópicos do Kafka transportam mensagens JSONL, tarefas do Airflow leem e gravam arquivos JSONL no armazenamento de objetos, e data warehouses ingerem JSONL com seus comandos nativos de carga em massa. Neste guia, você aprenderá padrões práticos para cada uma dessas etapas, com código pronto para produção.
Kafka + JSONL: streaming de eventos
O Apache Kafka é a base do ETL em tempo real. Os produtores emitem eventos como mensagens codificadas em JSONL (um objeto JSON por mensagem do Kafka), e os consumidores os leem linha por linha e os encaminham aos sistemas seguintes do pipeline. Como cada mensagem do Kafka corresponde a um único registro JSONL, o formato se encaixa perfeitamente na arquitetura de log do Kafka. A serialização é simples, e os consumidores podem interpretar cada mensagem de forma independente, sem precisar acumular dados em um buffer.
Um produtor do Kafka que serializa dicionários Python em mensagens codificadas em JSONL. Cada mensagem contém uma única linha JSON enviada a um tópico do Kafka. O value_serializer cuida da codificação automaticamente: basta passar um dict para o método send().
import json
from kafka import KafkaProducer
producer = KafkaProducer(
bootstrap_servers=['localhost:9092'],
value_serializer=lambda v: json.dumps(v).encode('utf-8'),
acks='all',
retries=3,
)
# Lê um arquivo JSONL e publica cada linha como uma mensagem Kafka
with open('events.jsonl', 'r') as f:
for line in f:
line = line.strip()
if not line:
continue
event = json.loads(line)
producer.send('etl-events', value=event)
producer.flush()
print('Todos os eventos publicados no Kafka')Um consumidor do Kafka que lê mensagens JSONL e as grava em lotes em um arquivo JSONL local. A gravação em lotes reduz o custo das operações de I/O e permite que os sistemas seguintes do pipeline processem blocos maiores de uma só vez. O consumidor só faz o commit dos offsets depois que o lote é gravado por completo, garantindo a entrega at-least-once.
import json
from kafka import KafkaConsumer
consumer = KafkaConsumer(
'etl-events',
bootstrap_servers=['localhost:9092'],
value_deserializer=lambda v: json.loads(v.decode('utf-8')),
group_id='etl-consumer-group',
enable_auto_commit=False,
auto_offset_reset='earliest',
)
BATCH_SIZE = 500
batch = []
for message in consumer:
batch.append(message.value)
if len(batch) >= BATCH_SIZE:
# Escreve o lote no arquivo JSONL
with open('output/batch.jsonl', 'a') as f:
for record in batch:
f.write(json.dumps(record) + '\n')
consumer.commit()
print(f'Lote de {len(batch)} registros commitado')
batch.clear()
# Flush dos registros restantes
if batch:
with open('output/batch.jsonl', 'a') as f:
for record in batch:
f.write(json.dumps(record) + '\n')
consumer.commit()Apache Airflow: orquestração de tarefas com JSONL
O Apache Airflow é a ferramenta padrão de orquestração para ETL em lotes. Um pipeline típico com JSONL no Airflow tem três etapas: extrair dados brutos para JSONL, transformar o arquivo JSONL (filtrar, enriquecer e reorganizar sua estrutura) e carregar o resultado em um data warehouse ou armazenamento de objetos. Cada etapa lê e grava arquivos JSONL, o que permite inspecionar os estados intermediários e reexecutar cada tarefa de forma independente.
Um DAG completo do Airflow que extrai dados de uma API, transforma esses dados em formato JSONL e carrega o resultado no armazenamento em nuvem. As tarefas trocam dados por meio de arquivos JSONL em um armazenamento compartilhado, facilitando a depuração e a reexecução do pipeline em caso de falha.
from airflow import DAG
from airflow.operators.python import PythonOperator
from airflow.providers.amazon.aws.hooks.s3 import S3Hook
from datetime import datetime, timedelta
import json
import requests
default_args = {
'owner': 'data-team',
'retries': 2,
'retry_delay': timedelta(minutes=5),
}
def extract(**context):
"""Extrai dados da API e escreve JSONL no disco local."""
ds = context['ds'] # data de execução: YYYY-MM-DD
response = requests.get(
'https://api.example.com/events',
params={'date': ds},
)
events = response.json()
path = f'/tmp/raw_{ds}.jsonl'
with open(path, 'w') as f:
for event in events:
f.write(json.dumps(event) + '\n')
return path
def transform(**context):
"""Lê JSONL bruto, filtra e enriquece, escreve JSONL limpo."""
ds = context['ds']
input_path = f'/tmp/raw_{ds}.jsonl'
output_path = f'/tmp/clean_{ds}.jsonl'
with open(input_path) as fin, open(output_path, 'w') as fout:
for line in fin:
record = json.loads(line)
if record.get('status') != 'valid':
continue
record['processed_at'] = datetime.utcnow().isoformat()
fout.write(json.dumps(record) + '\n')
return output_path
def load(**context):
"""Faz upload do JSONL limpo para S3."""
ds = context['ds']
local_path = f'/tmp/clean_{ds}.jsonl'
s3 = S3Hook(aws_conn_id='aws_default')
s3.load_file(
filename=local_path,
key=f'etl/events/{ds}/data.jsonl',
bucket_name='data-lake',
replace=True,
)
with DAG(
'jsonl_etl_pipeline',
default_args=default_args,
schedule_interval='@daily',
start_date=datetime(2026, 1, 1),
catchup=False,
) as dag:
t_extract = PythonOperator(task_id='extract', python_callable=extract)
t_transform = PythonOperator(task_id='transform', python_callable=transform)
t_load = PythonOperator(task_id='load', python_callable=load)
t_extract >> t_transform >> t_loadPara arquivos JSONL grandes que não cabem na memória, use uma transformação em streaming que processe uma linha por vez. Esse padrão mantém o consumo de memória constante, independentemente do tamanho do arquivo, e funciona bem em tarefas do Airflow nas quais os recursos dos workers podem ser limitados.
import json
from typing import Callable
def stream_transform(
input_path: str,
output_path: str,
transform_fn: Callable[[dict], dict | None],
batch_size: int = 5000,
) -> dict:
"""Transforma um arquivo JSONL por streaming com uma função definida pelo usuário.
Retorne None de transform_fn para pular um registro."""
stats = {'input': 0, 'output': 0, 'skipped': 0}
batch = []
with open(input_path) as fin, open(output_path, 'w') as fout:
for line in fin:
line = line.strip()
if not line:
continue
stats['input'] += 1
record = json.loads(line)
result = transform_fn(record)
if result is None:
stats['skipped'] += 1
continue
batch.append(json.dumps(result))
if len(batch) >= batch_size:
fout.write('\n'.join(batch) + '\n')
stats['output'] += len(batch)
batch.clear()
if batch:
fout.write('\n'.join(batch) + '\n')
stats['output'] += len(batch)
return stats
# Uso dentro de uma tarefa Airflow
def enrich(record):
if record.get('amount', 0) < 0:
return None # pula inválido
record['currency'] = record.get('currency', 'USD').upper()
return record
stats = stream_transform(
'/tmp/raw.jsonl',
'/tmp/enriched.jsonl',
transform_fn=enrich,
)
print(f'Processado: {stats}')Carga de JSONL em data warehouses
Data warehouses modernos oferecem suporte nativo à ingestão de arquivos JSONL. Snowflake, BigQuery e Redshift permitem carregar JSONL diretamente do armazenamento em nuvem, interpretar o JSON durante a carga e armazenar os resultados em tabelas estruturadas. Isso elimina a etapa intermediária de conversão para CSV e preserva os tipos de dados aninhados.
Snowflake
COPY INTOO Snowflake ingere JSONL com o comando COPY INTO a partir de stages do S3, GCS ou Azure Blob. Use a opção FILE_FORMAT com TYPE = 'JSON' para interpretar cada linha como um documento JSON separado. Colunas do tipo VARIANT armazenam dados semiestruturados de forma nativa.
BigQuery
NativoO BigQuery carrega arquivos JSONL do Google Cloud Storage com detecção automática de schema. O comando bq load com --source_format=NEWLINE_DELIMITED_JSON oferece suporte nativo a JSONL. O BigQuery também pode detectar automaticamente os tipos das colunas a partir dos valores JSON.
Redshift
COPYO Amazon Redshift permite carregar JSONL do S3 com o comando COPY e a opção FORMAT AS JSON. Você pode fornecer um arquivo JSONPaths para mapear as chaves JSON para as colunas da tabela e ter controle preciso sobre o processo de carga.
Carrega um arquivo JSONL de um stage S3 em uma tabela Snowflake. Cada linha se torna uma linha com uma coluna VARIANT contendo o JSON parseado. Você pode então achatar a coluna VARIANT em colunas tipadas usando SQL do Snowflake.
-- Cria um stage apontando para seu bucket S3
CREATE OR REPLACE STAGE etl_stage
URL = 's3://data-lake/etl/events/'
CREDENTIALS = (AWS_KEY_ID = '...' AWS_SECRET_KEY = '...')
FILE_FORMAT = (TYPE = 'JSON' STRIP_OUTER_ARRAY = FALSE);
-- Cria a tabela de destino
CREATE TABLE IF NOT EXISTS raw_events (
data VARIANT,
loaded_at TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP()
);
-- Carrega arquivos JSONL do stage
COPY INTO raw_events (data)
FROM @etl_stage
FILE_FORMAT = (TYPE = 'JSON')
PATTERN = '.*\.jsonl'
ON_ERROR = 'CONTINUE';
-- Consulta os dados carregados
SELECT
data:id::INT AS event_id,
data:user_id::STRING AS user_id,
data:event_type::STRING AS event_type,
data:timestamp::TIMESTAMP AS event_ts
FROM raw_events
LIMIT 10;Use o cliente Python do BigQuery para carregar um arquivo JSONL do Google Cloud Storage em uma tabela BigQuery. O cliente lida com detecção de schema, particionamento e relatório de erros. Essa abordagem se integra bem com tarefas Airflow.
from google.cloud import bigquery
client = bigquery.Client(project='my-project')
job_config = bigquery.LoadJobConfig(
source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
autodetect=True,
write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
max_bad_records=10,
)
# Carrega do GCS
uri = 'gs://data-lake/etl/events/2026-01-15/data.jsonl'
table_ref = 'my-project.analytics.raw_events'
load_job = client.load_table_from_uri(
uri,
table_ref,
job_config=job_config,
)
load_job.result() # Aguarda conclusão
table = client.get_table(table_ref)
print(f'Carregadas {load_job.output_rows} linhas')
print(f'A tabela agora tem {table.num_rows} linhas no total')Tolerância a falhas e idempotência
Pipelines ETL estão sujeitos a falhas. Conexões de rede caem, chamadas a APIs excedem o tempo limite e workers ficam sem memória. JSONL simplifica a recuperação porque cada linha é independente. Você pode salvar a posição do processamento (o número da linha) em um checkpoint, retomar a partir da última linha processada com sucesso e evitar o reprocessamento dos dados. Com gravações idempotentes, isso oferece semântica exactly-once mesmo com entrega at-least-once.
Um processador que usa checkpoints para acompanhar o progresso pelo número da linha. Se o pipeline falhar, o processamento é retomado a partir do último checkpoint confirmado, sem precisar reprocessar o arquivo inteiro. O checkpoint fica em um arquivo de texto simples que contém o número da última linha processada com sucesso.
import json
import os
def get_checkpoint(checkpoint_path: str) -> int:
"""Lê o último número de linha commitado."""
if os.path.exists(checkpoint_path):
with open(checkpoint_path) as f:
return int(f.read().strip())
return 0
def save_checkpoint(checkpoint_path: str, line_num: int):
"""Salva atomicamente o checkpoint atual."""
tmp = checkpoint_path + '.tmp'
with open(tmp, 'w') as f:
f.write(str(line_num))
os.replace(tmp, checkpoint_path) # atômico em POSIX
def process_with_checkpoint(
input_path: str,
output_path: str,
checkpoint_path: str,
batch_size: int = 1000,
):
"""Processa um arquivo JSONL com retomada baseada em checkpoint."""
start_line = get_checkpoint(checkpoint_path)
processed = 0
with open(input_path) as fin, \
open(output_path, 'a') as fout:
for line_num, line in enumerate(fin, 1):
if line_num <= start_line:
continue # pula linhas já processadas
line = line.strip()
if not line:
continue
record = json.loads(line)
# --- sua lógica de transformação ---
record['etl_version'] = 'v2'
fout.write(json.dumps(record) + '\n')
processed += 1
if processed % batch_size == 0:
fout.flush()
save_checkpoint(checkpoint_path, line_num)
print(f'Checkpoint na linha {line_num}')
# Checkpoint final
save_checkpoint(checkpoint_path, line_num)
print(f'Concluído. Processados {processed} registros a partir da linha {start_line + 1}')
# Uso
process_with_checkpoint(
'input.jsonl',
'output.jsonl',
'checkpoint.txt',
batch_size=5000,
)O padrão de checkpoint funciona em qualquer etapa de um pipeline com JSONL. Para consumidores do Kafka, substitua o checkpoint em arquivo por offsets confirmados com commit. No Airflow, armazene o checkpoint no XCom ou em um banco de dados externo para que as tarefas reexecutadas retomem o processamento na posição correta. O ponto central é que o formato do JSONL, organizado em linhas, simplifica o controle da posição: um único inteiro (o número da linha ou o offset em bytes) basta para retomar o processamento.
Valide seu JSONL antes da carga
Detecte registros malformados antes que eles cheguem ao seu pipeline. Use nossas ferramentas online gratuitas para validar, visualizar e converter arquivos JSONL no navegador.
Aprenda a transmitir dados JSONL em tempo real usando Node.js, Python, Server-Sent Events e WebSockets. Crie pipelines de streaming para logs, métricas e feeds de dados em tempo real.
Aprenda a importar e exportar dados JSONL com bancos de dados PostgreSQL, MongoDB, MySQL e SQLite.
Aprenda a validar arquivos JSONL usando JSON Schema. Abrange ferramentas Python, Node.js, CLI e automacao CI/CD.
Estratégias para processar gigabytes de dados JSONL: leitura por streaming, gerenciamento de memória, divisão de arquivos, compressão e ferramentas online.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.