JSONL en pipelines ETL: Kafka, Airflow y data warehouses
Una guía práctica para usar JSONL (JSON Lines) como formato de intercambio en pipelines ETL modernos. Aprende a producir y consumir eventos JSONL en Kafka, a orquestar transformaciones JSONL mediante DAGs de Airflow y a cargar datos JSONL en Snowflake, BigQuery y Redshift.
Por qué JSONL es el formato ideal para el intercambio de datos en ETL
Los pipelines de extracción, transformación y carga (ETL) trasladan datos entre sistemas que rara vez comparten el mismo esquema. JSONL resulta especialmente adecuado para esta tarea porque cada línea es un documento JSON independiente y completo. No hay cabeceras que puedan perderse, delimitadores que haya que escapar ni registros de varias líneas que deban reconstruirse tras un fallo parcial. Cada línea se puede validar, transformar y dirigir a su destino de forma independiente, justo lo que necesitan sistemas distribuidos como Kafka y Airflow.
A diferencia de CSV, JSONL conserva las estructuras anidadas, los arrays y los valores con sus tipos de datos sin ambigüedades. A diferencia de Parquet o Avro, se puede leer directamente y no requiere herramientas especiales para inspeccionarlo. Estas características hacen de JSONL una opción natural para conectar las etapas de un pipeline: los topics de Kafka transportan mensajes JSONL, las tareas de Airflow leen y escriben archivos JSONL en almacenamiento de objetos, y los data warehouses cargan JSONL mediante sus comandos nativos de carga masiva. En esta guía aprenderás patrones concretos para cada etapa, con código listo para producción.
Kafka + JSONL: streaming de eventos
Apache Kafka es la base del ETL en tiempo real. Los productores emiten eventos en mensajes codificados en JSONL (un objeto JSON por mensaje de Kafka), y los consumidores los leen línea a línea para enviarlos a los siguientes sistemas del flujo. Como cada mensaje de Kafka contiene un único registro JSONL, el formato encaja perfectamente con la arquitectura de Kafka basada en logs. La serialización es sencilla y los consumidores pueden analizar cada mensaje de forma independiente, sin tener que acumular datos en un búfer.
Un productor de Kafka que serializa diccionarios de Python en mensajes codificados en JSONL. Cada mensaje contiene una sola línea JSON que se envía a un topic de Kafka. value_serializer se encarga de la codificación automáticamente, por lo que solo tienes que pasar un dict al 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,
)
# Read a JSONL file and publish each line as a Kafka message
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('All events published to Kafka')Un consumidor de Kafka que lee mensajes JSONL y los escribe por lotes en un archivo JSONL local. Agrupar las escrituras en lotes reduce la sobrecarga de E/S y permite que los siguientes sistemas del flujo procesen bloques más grandes de una sola vez. El consumidor solo confirma los offsets cuando se ha terminado de escribir todo el lote, lo que garantiza la entrega al menos una vez.
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:
# Write batch to JSONL file
with open('output/batch.jsonl', 'a') as f:
for record in batch:
f.write(json.dumps(record) + '\n')
consumer.commit()
print(f'Committed batch of {len(batch)} records')
batch.clear()
# Flush remaining records
if batch:
with open('output/batch.jsonl', 'a') as f:
for record in batch:
f.write(json.dumps(record) + '\n')
consumer.commit()Apache Airflow: orquestación de tareas JSONL
Apache Airflow es la herramienta de referencia para orquestar procesos ETL por lotes. Un pipeline de Airflow basado en JSONL suele tener tres etapas: extraer los datos sin procesar a JSONL, transformar el archivo JSONL (filtrar, enriquecer y reestructurar los datos) y cargar el resultado en un data warehouse o en almacenamiento de objetos. Cada etapa lee y escribe archivos JSONL, lo que permite inspeccionar el estado intermedio y volver a ejecutar cada tarea por separado.
Un DAG completo de Airflow que extrae datos de una API, los transforma en formato JSONL y carga el resultado en almacenamiento en la nube. Las tareas se comunican mediante archivos JSONL en almacenamiento compartido, lo que facilita depurar el pipeline y reintentar su ejecución.
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):
"""Extract data from API and write JSONL to local disk."""
ds = context['ds'] # execution date: 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):
"""Read raw JSONL, filter and enrich, write cleaned JSONL."""
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):
"""Upload cleaned JSONL to 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 archivos JSONL que no caben en memoria, usa una transformación en streaming que procese una línea a la vez. Este patrón mantiene constante el consumo de memoria, independientemente del tamaño del archivo, y funciona bien en tareas de Airflow donde los recursos de los workers pueden 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:
"""Stream-transform a JSONL file with a user-defined function.
Return None from transform_fn to skip a record."""
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
# Usage inside an Airflow task
def enrich(record):
if record.get('amount', 0) < 0:
return None # skip invalid
record['currency'] = record.get('currency', 'USD').upper()
return record
stats = stream_transform(
'/tmp/raw.jsonl',
'/tmp/enriched.jsonl',
transform_fn=enrich,
)
print(f'Processed: {stats}')Carga de JSONL en data warehouses
Los data warehouses modernos ofrecen soporte nativo para la ingesta de archivos JSONL. Snowflake, BigQuery y Redshift permiten cargar JSONL directamente desde almacenamiento en la nube, analizar el JSON durante la carga y guardar los resultados en tablas estructuradas. Así se evita un paso intermedio de conversión a CSV y se conservan los tipos de datos anidados.
Snowflake
COPY INTOSnowflake carga JSONL con el comando COPY INTO desde stages de S3, GCS o Azure Blob. Usa la opción FILE_FORMAT con TYPE = 'JSON' para analizar cada línea como un documento JSON independiente. El tipo de columna VARIANT permite almacenar datos semiestructurados de forma nativa.
BigQuery
NativoBigQuery carga archivos JSONL desde Google Cloud Storage y detecta el esquema automáticamente. El comando bq load con --source_format=NEWLINE_DELIMITED_JSON admite JSONL de forma nativa. BigQuery también puede detectar automáticamente los tipos de las columnas a partir de los valores JSON.
Redshift
COPYAmazon Redshift permite cargar JSONL desde S3 mediante el comando COPY con FORMAT AS JSON. Puedes proporcionar un archivo JSONPaths para asignar las claves JSON a las columnas de la tabla y controlar con precisión el proceso de carga.
Carga un archivo JSONL desde un stage de S3 en una tabla de Snowflake. Cada linea se convierte en una fila con una columna VARIANT que contiene el JSON analizado. Luego puedes aplanar la columna VARIANT en columnas tipadas usando SQL de Snowflake.
-- Create a stage pointing to your S3 bucket
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);
-- Create the target table
CREATE TABLE IF NOT EXISTS raw_events (
data VARIANT,
loaded_at TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP()
);
-- Load JSONL files from the stage
COPY INTO raw_events (data)
FROM @etl_stage
FILE_FORMAT = (TYPE = 'JSON')
PATTERN = '.*\.jsonl'
ON_ERROR = 'CONTINUE';
-- Query the loaded data
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;Usa el cliente Python de BigQuery para cargar un archivo JSONL desde Google Cloud Storage en una tabla de BigQuery. El cliente maneja la deteccion de esquema, particionamiento e informes de errores. Este enfoque se integra bien con tareas de 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,
)
# Load from 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() # Wait for completion
table = client.get_table(table_ref)
print(f'Loaded {load_job.output_rows} rows')
print(f'Table now has {table.num_rows} total rows')Tolerancia a fallos e idempotencia
Los pipelines ETL también fallan: las conexiones de red se cortan, las llamadas a las APIs agotan el tiempo de espera y los workers se quedan sin memoria. JSONL facilita la recuperación porque cada línea es independiente. Puedes guardar la posición de procesamiento (el número de línea) en un checkpoint, reanudar desde la última línea procesada correctamente y evitar volver a procesar datos. Si además usas escrituras idempotentes, obtienes una semántica de procesamiento exactamente una vez, incluso cuando la entrega se realiza al menos una vez.
Un procesador que utiliza checkpoints para registrar el progreso por número de línea. Si el pipeline falla, retoma el procesamiento desde el último checkpoint confirmado en lugar de volver a procesar todo el archivo. El checkpoint se guarda en un archivo de texto sencillo que contiene el número de la última línea procesada correctamente.
import json
import os
def get_checkpoint(checkpoint_path: str) -> int:
"""Read the last committed line number."""
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):
"""Atomically save the current checkpoint."""
tmp = checkpoint_path + '.tmp'
with open(tmp, 'w') as f:
f.write(str(line_num))
os.replace(tmp, checkpoint_path) # atomic on POSIX
def process_with_checkpoint(
input_path: str,
output_path: str,
checkpoint_path: str,
batch_size: int = 1000,
):
"""Process a JSONL file with checkpoint-based resumption."""
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 # skip already-processed lines
line = line.strip()
if not line:
continue
record = json.loads(line)
# --- your transform logic ---
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 at line {line_num}')
# Final checkpoint
save_checkpoint(checkpoint_path, line_num)
print(f'Done. Processed {processed} records from line {start_line + 1}')
# Usage
process_with_checkpoint(
'input.jsonl',
'output.jsonl',
'checkpoint.txt',
batch_size=5000,
)El patrón de checkpoints sirve para cualquier etapa de un pipeline con JSONL. En los consumidores de Kafka, sustituye el checkpoint del archivo por los offsets confirmados. En Airflow, guarda el checkpoint en XCom o en una base de datos externa para que las tareas se reanuden desde la posición correcta al reintentarlas. La clave es que el formato de JSONL, organizado por líneas, simplifica al máximo el seguimiento de la posición: basta con un entero (el número de línea o el desplazamiento en bytes) para reanudar el procesamiento.
Valida tus archivos JSONL antes de cargarlos
Detecta los registros mal formados antes de que lleguen a tu pipeline. Usa nuestras herramientas gratuitas en línea para validar, ver y convertir archivos JSONL en tu navegador.
Aprende a transmitir datos JSONL en tiempo real con Node.js, Python, Server-Sent Events y WebSockets. Crea pipelines de streaming para logs, métricas y flujos de datos en directo.
Aprende a importar y exportar datos JSONL con bases de datos PostgreSQL, MongoDB, MySQL y SQLite.
Aprende a validar archivos JSONL usando JSON Schema. Cubre Python, Node.js, herramientas CLI y automatizacion CI/CD.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.