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().
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.
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.
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_loadPer 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.
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 INTOSnowflake 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
NativoBigQuery 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
COPYAmazon 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.
-- 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.
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.
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.
Valida i file JSONL prima di caricarli
Individua i record malformati prima che entrino nella pipeline. Usa i nostri strumenti online gratuiti per validare, visualizzare e convertire file JSONL nel browser.
Impara a elaborare dati JSONL in streaming in tempo reale con Node.js, Python, Server-Sent Events e WebSocket. Crea pipeline di streaming per log, metriche e flussi di dati in tempo reale.
Scopri come importare ed esportare dati JSONL con database PostgreSQL, MongoDB, MySQL e SQLite.
Scopri come validare file JSONL usando JSON Schema. Copre Python, Node.js, strumenti CLI e automazione CI/CD.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.