Von Jerry Fan

JSONL in ETL-Pipelines: Kafka, Airflow & Data Warehouses

Ein Praxisleitfaden zu JSONL (JSON Lines) als Austauschformat in modernen ETL-Pipelines. Erfahren Sie, wie Sie JSONL-Events mit Kafka senden und empfangen, JSONL-Transformationen in Airflow-DAGs orchestrieren und JSONL-Daten in Snowflake, BigQuery und Redshift laden.

Warum JSONL das ideale Austauschformat für ETL ist

Extract-Transform-Load-Pipelines (ETL) übertragen Daten zwischen Systemen, die nur selten dasselbe Schema verwenden. JSONL eignet sich dafür besonders gut, weil jede Zeile ein eigenständiges JSON-Dokument enthält. Es gibt keine Kopfzeilen, die verloren gehen können, keine Trennzeichen, die maskiert werden müssen, und keine mehrzeiligen Datensätze, die nach einem Teilausfall wieder zusammengesetzt werden müssen. Jede Zeile lässt sich unabhängig validieren, transformieren und weiterleiten – genau das brauchen verteilte Systeme wie Kafka und Airflow.

Anders als CSV erhält JSONL verschachtelte Strukturen, Arrays und die Datentypen der Werte eindeutig. Anders als Parquet oder Avro ist JSONL direkt lesbar und lässt sich ohne spezielle Tools prüfen. Damit eignet sich JSONL als Bindeglied zwischen den Pipeline-Stufen: Kafka-Topics transportieren JSONL-Nachrichten, Airflow-Tasks lesen JSONL-Dateien aus dem Objektspeicher und schreiben sie dorthin zurück, und Data Warehouses importieren JSONL mit ihren nativen Bulk-Load-Befehlen. Dieser Leitfaden zeigt für jede dieser Stufen konkrete Vorgehensweisen mit produktionsreifen Codebeispielen.

Kafka + JSONL: Event-Streaming

Apache Kafka bildet das Rückgrat von Echtzeit-ETL-Pipelines. Producer senden Events als JSONL-kodierte Nachrichten (ein JSON-Objekt pro Kafka-Nachricht), und Consumer lesen sie zeilenweise in nachgelagerte Systeme ein. Da jede Kafka-Nachricht genau einem JSONL-Datensatz entspricht, passt das Format optimal zur logbasierten Architektur von Kafka. Die Serialisierung ist einfach, und Consumer können jede Nachricht unabhängig parsen, ohne sie zwischenspeichern zu müssen.

Dieser Kafka-Producer serialisiert Python-Dictionaries als JSONL-kodierte Nachrichten. Jede Nachricht besteht aus einer einzelnen JSON-Zeile, die an ein Kafka-Topic gesendet wird. value_serializer übernimmt die Kodierung automatisch. Sie müssen der send()-Methode also nur ein dict übergeben.

JSONL-Producer für Kafka
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,
)


# Eine JSONL-Datei lesen und jede Zeile als Kafka-Nachricht veröffentlichen
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')

Dieser Kafka-Consumer liest JSONL-Nachrichten und schreibt sie in Batches in eine lokale JSONL-Datei. Das reduziert den I/O-Overhead und ermöglicht nachgelagerten Systemen, größere Datenblöcke auf einmal zu verarbeiten. Der Consumer bestätigt die Offsets erst, wenn ein Batch vollständig geschrieben ist. So ist eine At-Least-Once-Zustellung gewährleistet.

JSONL-Consumer für Kafka mit gebündelten Schreibvorgängen
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:
        # Batch in JSONL-Datei schreiben
        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()


# Verbleibende Datensätze flushen
if batch:
    with open('output/batch.jsonl', 'a') as f:
        for record in batch:
            f.write(json.dumps(record) + '\n')
    consumer.commit()

Apache Airflow: JSONL-Tasks orchestrieren

Apache Airflow ist das Standardwerkzeug zur Orchestrierung von Batch-ETL-Pipelines. Eine typische Airflow-Pipeline mit JSONL besteht aus drei Stufen: Rohdaten extrahieren und als JSONL speichern, die JSONL-Datei transformieren (filtern, anreichern, umstrukturieren) und das Ergebnis in ein Data Warehouse oder einen Objektspeicher laden. Jede Stufe liest und schreibt JSONL-Dateien. So lassen sich Zwischenergebnisse prüfen und einzelne Tasks unabhängig erneut ausführen.

Dieser vollständige Airflow-DAG extrahiert Daten aus einer API, transformiert sie im JSONL-Format und lädt das Ergebnis in den Cloud-Speicher. Die Tasks tauschen ihre Daten über JSONL-Dateien auf einem gemeinsam genutzten Speicher aus. Das erleichtert die Fehlersuche und die erneute Ausführung bei Fehlern.

Airflow-DAG: JSONL-ETL-Pipeline
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):
    """Daten von der API extrahieren und als JSONL auf die lokale Festplatte schreiben."""
    ds = context['ds']  # Ausführungsdatum: 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):
    """Roh-JSONL lesen, filtern und anreichern, bereinigtes JSONL schreiben."""
    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):
    """Bereinigtes JSONL nach S3 hochladen."""
    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

Verwenden Sie für große JSONL-Dateien, die nicht in den Arbeitsspeicher passen, eine Streaming-Transformation, die jeweils nur eine Zeile verarbeitet. So bleibt der Speicherverbrauch unabhängig von der Dateigröße konstant. Das eignet sich besonders für Airflow-Tasks, deren Worker möglicherweise nur begrenzte Ressourcen haben.

Airflow-Task zur zeilenweisen JSONL-Transformation
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:
    """JSONL-Datei mit benutzerdefinierter Funktion stream-transformieren.
    Geben Sie None von transform_fn zurück, um einen Datensatz zu überspringen."""
    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


# Verwendung innerhalb eines Airflow-Tasks
def enrich(record):
    if record.get('amount', 0) < 0:
        return None  # Ungültige überspringen
    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}')

JSONL in Data Warehouses laden

Moderne Data Warehouses unterstützen den Import von JSONL-Dateien direkt. Snowflake, BigQuery und Redshift können JSONL aus dem Cloud-Speicher laden, die JSON-Daten dabei parsen und die Ergebnisse in strukturierten Tabellen speichern. Eine vorherige Konvertierung in CSV entfällt, und verschachtelte Datentypen bleiben erhalten.

Snowflake

COPY INTO

Snowflake importiert JSONL mit dem Befehl COPY INTO aus Stages für S3, GCS oder Azure Blob. Mit der Option FILE_FORMAT und TYPE = 'JSON' wird jede Zeile als eigenständiges JSON-Dokument geparst. Der Spaltentyp VARIANT unterstützt semistrukturierte Daten nativ.

BigQuery

Nativ

BigQuery lädt JSONL-Dateien aus Google Cloud Storage und erkennt dabei das Schema automatisch. Der Befehl bq load unterstützt JSONL mit --source_format=NEWLINE_DELIMITED_JSON nativ. Auch die Spaltentypen kann BigQuery anhand der JSON-Werte automatisch erkennen.

Redshift

COPY

Amazon Redshift lädt JSONL aus S3 mit dem Befehl COPY und der Option FORMAT AS JSON. Mit einer JSONPaths-Datei können Sie JSON-Schlüssel gezielt den Tabellenspalten zuordnen und den Import so im Detail steuern.

Laden Sie eine JSONL-Datei aus einer S3-Stage in eine Snowflake-Tabelle. Jede Zeile wird zu einer Zeile mit einer VARIANT-Spalte, die das geparste JSON enthält. Anschließend können Sie die VARIANT-Spalte mit Snowflake SQL in typisierte Spalten auffalten.

Snowflake: COPY JSONL aus S3
-- Eine Stage erstellen, die auf Ihren S3-Bucket zeigt
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);


-- Zieltabelle erstellen
CREATE TABLE IF NOT EXISTS raw_events (
  data VARIANT,
  loaded_at TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP()
);


-- JSONL-Dateien aus der Stage laden
COPY INTO raw_events (data)
  FROM @etl_stage
  FILE_FORMAT = (TYPE = 'JSON')
  PATTERN = '.*\.jsonl'
  ON_ERROR = 'CONTINUE';


-- Geladene Daten abfragen
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;

Verwenden Sie den BigQuery-Python-Client, um eine JSONL-Datei aus Google Cloud Storage in eine BigQuery-Tabelle zu laden. Der Client übernimmt Schema-Erkennung, Partitionierung und Fehlerberichterstattung. Dieser Ansatz lässt sich gut mit Airflow-Tasks integrieren.

BigQuery: JSONL mit Python-Client laden
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,
)


# Aus GCS laden
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()  # Auf Abschluss warten


table = client.get_table(table_ref)
print(f'Loaded {load_job.output_rows} rows')
print(f'Table now has {table.num_rows} total rows')

Fehlertoleranz und Idempotenz

Auch ETL-Pipelines fallen aus: Netzwerkverbindungen brechen ab, API-Aufrufe laufen in einen Timeout, und Workern geht der Arbeitsspeicher aus. JSONL erleichtert den Wiederanlauf, weil jede Zeile unabhängig ist. Sie können die aktuelle Position (die Zeilennummer) als Checkpoint speichern und die Verarbeitung nach der letzten erfolgreich verarbeiteten Zeile fortsetzen. Bereits verarbeitete Daten müssen so nicht erneut verarbeitet werden. In Verbindung mit idempotenten Schreibvorgängen erreichen Sie damit Exactly-Once-Semantik auch bei At-Least-Once-Zustellung.

Diese Verarbeitungslösung hält den Fortschritt anhand der Zeilennummer fest. Fällt die Pipeline aus, setzt sie die Verarbeitung am letzten gespeicherten Checkpoint fort, statt die gesamte Datei erneut zu verarbeiten. Der Checkpoint liegt in einer einfachen Textdatei, die die Nummer der zuletzt erfolgreich verarbeiteten Zeile enthält.

JSONL mit Checkpoints verarbeiten
import json
import os


def get_checkpoint(checkpoint_path: str) -> int:
    """Letzte committete Zeilennummer lesen."""
    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):
    """Aktuellen Checkpoint atomar speichern."""
    tmp = checkpoint_path + '.tmp'
    with open(tmp, 'w') as f:
        f.write(str(line_num))
    os.replace(tmp, checkpoint_path)  # atomar auf POSIX


def process_with_checkpoint(
    input_path: str,
    output_path: str,
    checkpoint_path: str,
    batch_size: int = 1000,
):
    """JSONL-Datei mit checkpoint-basierter Fortsetzung verarbeiten."""
    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  # Bereits verarbeitete Zeilen überspringen
            line = line.strip()
            if not line:
                continue
            record = json.loads(line)
            # --- Ihre Transformationslogik ---
            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}')


        # Finaler Checkpoint
        save_checkpoint(checkpoint_path, line_num)


    print(f'Done. Processed {processed} records from line {start_line + 1}')


# Verwendung
process_with_checkpoint(
    'input.jsonl',
    'output.jsonl',
    'checkpoint.txt',
    batch_size=5000,
)

Das Checkpoint-Prinzip lässt sich in jeder Stufe einer JSONL-Pipeline einsetzen. Bei Kafka-Consumern verwenden Sie statt eines Checkpoints in einer Datei die bestätigten Offsets. In Airflow speichern Sie den Checkpoint in XCom oder einer externen Datenbank, damit Tasks bei einer erneuten Ausführung an der richtigen Stelle fortfahren. Entscheidend ist das zeilenbasierte Format von JSONL: Um die Position festzuhalten und die Verarbeitung fortzusetzen, genügt eine einzige Ganzzahl – die Zeilennummer oder der Byte-Offset.

JSONL-Dateien sofort prüfen

JSONL-Dateien bis zu 1 GB direkt im Browser anzeigen, validieren und konvertieren. Ohne Upload, 100 % privat.

Häufig gestellte Fragen

Quellen