Por Jerry Fan

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().

Productor de Kafka para JSONL
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.

Consumidor de Kafka para JSONL con escritura por lotes
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.

DAG de Airflow: pipeline ETL con JSONL
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_load

Para 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.

Tarea de transformación de JSONL en streaming
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 INTO

Snowflake 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

Nativo

BigQuery 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

COPY

Amazon 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.

Snowflake: COPY JSONL desde S3
-- 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.

BigQuery: Cargar JSONL con cliente Python
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.

Procesamiento de JSONL con checkpoints
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.

Inspecciona archivos JSONL al instante

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin necesidad de subirlos a ningún servidor y con un 100% de privacidad.

Preguntas frecuentes

Referencias