Di Jerry Fan

JSONL nelle pipeline ETL: Kafka, Airflow e data warehouse

Una guida pratica per usare JSONL (JSON Lines) come formato di interscambio nelle moderne pipeline ETL. Impara a produrre e consumare eventi JSONL in Kafka, a orchestrare le trasformazioni JSONL nei DAG di Airflow e a caricare dati JSONL in Snowflake, BigQuery e Redshift.

Perché JSONL è il formato di interscambio ideale per le pipeline ETL

Le pipeline Extract-Transform-Load (ETL) trasferiscono dati tra sistemi che raramente condividono lo stesso schema. JSONL si presta particolarmente bene a questo compito perché ogni riga è un documento JSON autonomo. Non ci sono intestazioni che rischiano di andare perse, delimitatori che richiedono sequenze di escape o record su più righe da ricomporre dopo un errore parziale. Ogni riga può essere validata, trasformata e instradata in modo indipendente: proprio ciò che serve ai sistemi distribuiti come Kafka e Airflow.

A differenza di CSV, JSONL mantiene strutture nidificate, array e valori tipizzati senza ambiguità. Rispetto a Parquet o Avro, è leggibile direttamente e non richiede strumenti specifici per esaminarne il contenuto. Queste caratteristiche ne fanno una scelta naturale per collegare le fasi di una pipeline: i topic Kafka trasportano messaggi JSONL, i task di Airflow leggono e scrivono file JSONL su object storage e i data warehouse li importano tramite i propri comandi nativi di caricamento in blocco. In questa guida imparerai a implementare ciascuna di queste fasi con pattern concreti e codice pronto per la produzione.

Kafka + JSONL: streaming di eventi

Apache Kafka è alla base delle pipeline ETL in tempo reale. I producer pubblicano eventi come messaggi codificati in JSONL (un oggetto JSON per messaggio Kafka) e i consumer li leggono riga per riga per trasferirli ai sistemi a valle. Ogni messaggio Kafka corrisponde a un singolo record JSONL: il formato si adatta quindi perfettamente all'architettura di Kafka basata su log. La serializzazione è semplice e i consumer possono eseguire il parsing di ciascun messaggio in modo indipendente, senza ricorrere al buffering.

Un producer Kafka che serializza dizionari Python in messaggi JSONL. Ogni messaggio contiene una singola riga JSON e viene inviato a un topic Kafka. Il parametro value_serializer gestisce automaticamente la codifica: ti basta passare un dict al metodo send().

Producer Kafka per 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 consumer Kafka che legge messaggi JSONL e li scrive in batch in un file JSONL locale. La scrittura in batch riduce l'overhead di I/O e permette ai sistemi a valle di elaborare blocchi di dati più grandi in una sola volta. Il consumer esegue il commit degli offset solo dopo aver completato la scrittura del batch, garantendo la consegna at-least-once.

Consumer Kafka per JSONL con scrittura in batch
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: orchestrare i task JSONL

Apache Airflow è lo strumento di riferimento per orchestrare le pipeline ETL batch. Una tipica pipeline Airflow basata su JSONL prevede tre fasi: estrarre i dati grezzi in formato JSONL, trasformare il file JSONL (filtrando, arricchendo e ristrutturando i dati) e caricare il risultato in un data warehouse o in un object store. Ogni fase legge e scrive file JSONL: puoi così esaminare lo stato intermedio e rieseguire i singoli task in modo indipendente.

Un DAG di Airflow completo che estrae dati da un'API, li trasforma in formato JSONL e carica il risultato su cloud storage. I task si scambiano i dati tramite file JSONL salvati su storage condiviso, semplificando il debug e la riesecuzione in caso di errore.

DAG di Airflow: una 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

Per i file JSONL troppo grandi per essere caricati in memoria, usa una trasformazione in streaming che elabori una riga alla volta. Questo pattern mantiene costante l'uso della memoria, indipendentemente dalle dimensioni del file, ed è adatto ai task di Airflow, dove i worker possono disporre di risorse limitate.

Task di trasformazione JSONL in 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}')

Caricare JSONL nei data warehouse

I moderni data warehouse offrono un supporto nativo completo per l'importazione di file JSONL. Snowflake, BigQuery e Redshift possono caricare file JSONL direttamente da cloud storage, eseguire il parsing del JSON durante il caricamento e salvare i risultati in tabelle strutturate. Non serve quindi un passaggio intermedio di conversione in CSV e i tipi di dati nidificati vengono preservati.

Snowflake

COPY INTO

Snowflake importa file JSONL tramite il comando COPY INTO da stage su S3, GCS o Azure Blob. Usa l'opzione FILE_FORMAT con TYPE = 'JSON' per interpretare ogni riga come un documento JSON distinto. Il tipo di colonna VARIANT consente di memorizzare nativamente dati semistrutturati.

BigQuery

Nativo

BigQuery carica file JSONL da Google Cloud Storage rilevando automaticamente lo schema. Il comando bq load con --source_format=NEWLINE_DELIMITED_JSON gestisce JSONL in modo nativo. BigQuery può anche dedurre automaticamente i tipi delle colonne dai valori JSON.

Redshift

COPY

Amazon Redshift permette di caricare file JSONL da S3 tramite il comando COPY con FORMAT AS JSON. Puoi fornire un file JSONPaths per associare le chiavi JSON alle colonne della tabella e controllare nel dettaglio il processo di caricamento.

Carica un file JSONL da uno stage S3 in una tabella Snowflake. Ogni riga diventa una riga con una colonna VARIANT contenente il JSON analizzato. Puoi poi appiattire la colonna VARIANT in colonne tipizzate usando SQL di Snowflake.

Snowflake: COPY JSONL da 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 il client Python di BigQuery per caricare un file JSONL da Google Cloud Storage in una tabella BigQuery. Il client gestisce il rilevamento dello schema, il partizionamento e la segnalazione degli errori. Questo approccio si integra bene con i task Airflow.

BigQuery: Carica JSONL con il Client 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')

Tolleranza ai guasti e idempotenza

Nelle pipeline ETL possono verificarsi errori: le connessioni di rete si interrompono, le API vanno in timeout e i worker esauriscono la memoria. Con JSONL è semplice riprendere l'elaborazione, perché ogni riga è indipendente. Puoi salvare la posizione raggiunta (il numero di riga) in un checkpoint, ripartire dall'ultima riga elaborata correttamente ed evitare di elaborare di nuovo gli stessi dati. Abbinando questo meccanismo a scritture idempotenti, ottieni una semantica exactly-once anche con consegna at-least-once.

Un sistema di elaborazione che tiene traccia dell'avanzamento tramite checkpoint basati sul numero di riga. Se la pipeline si interrompe per un errore, riparte dall'ultimo checkpoint confermato senza rielaborare l'intero file. Il checkpoint è un semplice file di testo che contiene il numero dell'ultima riga elaborata correttamente.

Elaborazione JSONL con checkpoint
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,
)

Il pattern dei checkpoint si applica a qualsiasi fase di una pipeline JSONL. Per i consumer Kafka, sostituisci il checkpoint su file con gli offset di cui è stato eseguito il commit. In Airflow, salva il checkpoint in XCom o in un database esterno, così i task rieseguiti dopo un errore possono ripartire dalla posizione corretta. Il punto è che il formato di JSONL, organizzato per righe, rende semplicissimo tenere traccia della posizione: per riprendere l'elaborazione basta un intero, che sia il numero di riga o l'offset in byte.

Esamina subito i file JSONL

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel browser. Non devi caricare alcun file su un server: la privacy è garantita al 100%.

Domande frequenti

Riferimenti