Autor: Jerry Fan

JSONL w potokach ETL: Kafka, Airflow i hurtownie danych

Praktyczny przewodnik po wykorzystaniu JSONL (JSON Lines) jako formatu wymiany danych w nowoczesnych potokach ETL. Dowiedz się, jak publikować i odbierać zdarzenia JSONL w Kafce, sterować transformacjami JSONL w DAG-ach Airflow oraz ładować dane JSONL do Snowflake, BigQuery i Redshift.

Dlaczego JSONL to idealny format wymiany danych w ETL

Potoki Extract-Transform-Load (ETL) przenoszą dane między systemami, które rzadko korzystają z tego samego schematu. JSONL świetnie się do tego nadaje, bo każda linia jest samodzielnym dokumentem JSON. Nie ma nagłówków, które można zgubić, separatorów wymagających znaków ucieczki ani wieloliniowych rekordów, które trzeba składać na nowo po częściowej awarii. Każdą linię można niezależnie walidować, przekształcać i kierować do odpowiedniego systemu — właśnie tego potrzebują systemy rozproszone, takie jak Kafka i Airflow.

W odróżnieniu od CSV JSONL jednoznacznie zachowuje zagnieżdżone struktury, tablice i typy wartości. W odróżnieniu od Parquet czy Avro jest czytelny dla człowieka i nie wymaga specjalnych narzędzi do przeglądania danych. Dzięki tym właściwościom JSONL jest naturalnym wyborem do wymiany danych między etapami potoku: topiki Kafki przenoszą wiadomości JSONL, zadania Airflow odczytują i zapisują pliki JSONL w magazynie obiektowym, a hurtownie danych wczytują je za pomocą wbudowanych poleceń ładowania masowego. W tym przewodniku poznasz konkretne wzorce dla każdego z tych etapów wraz z kodem gotowym do użycia na produkcji.

Kafka + JSONL: strumieniowe przesyłanie zdarzeń

Apache Kafka stanowi podstawę potoków ETL działających w czasie rzeczywistym. Producenci publikują zdarzenia jako wiadomości w formacie JSONL (jeden obiekt JSON na wiadomość Kafki), a konsumenci odczytują je linia po linii i przekazują do kolejnych systemów. Każda wiadomość Kafki odpowiada jednemu rekordowi JSONL, więc format ten doskonale pasuje do architektury Kafki opartej na dzienniku. Serializacja jest prosta, a konsumenci mogą parsować każdą wiadomość niezależnie, bez buforowania.

Producent Kafki, który serializuje słowniki Pythona do wiadomości w formacie JSONL. Każda wiadomość to pojedyncza linia JSON wysyłana do topiku Kafki. value_serializer automatycznie obsługuje kodowanie, więc wystarczy przekazać dict do metody send().

Producent wiadomości JSONL w Kafce
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,
)


# Odczytaj plik JSONL i opublikuj kazda linie jako wiadomosc Kafka
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('Wszystkie zdarzenia opublikowane do Kafka')

Konsument Kafki, który odczytuje wiadomości JSONL i zapisuje je partiami do lokalnego pliku JSONL. Zapis wsadowy zmniejsza narzut operacji I/O i pozwala kolejnym systemom przetwarzać większe porcje danych naraz. Konsument zatwierdza offsety dopiero po zapisaniu całej partii, zapewniając dostarczenie każdej wiadomości co najmniej raz.

Konsument wiadomości JSONL w Kafce z zapisem wsadowym
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:
        # Zapisz partie do pliku JSONL
        with open('output/batch.jsonl', 'a') as f:
            for record in batch:
                f.write(json.dumps(record) + '\n')
        consumer.commit()
        print(f'Zatwierdzona partia {len(batch)} rekordow')
        batch.clear()


# Oproznij pozostale rekordy
if batch:
    with open('output/batch.jsonl', 'a') as f:
        for record in batch:
            f.write(json.dumps(record) + '\n')
    consumer.commit()

Apache Airflow: orkiestracja zadań przetwarzających JSONL

Apache Airflow to standardowe narzędzie do orkiestracji wsadowych procesów ETL. Typowy potok Airflow oparty na JSONL składa się z trzech etapów: pobrania surowych danych i zapisania ich w JSONL, transformacji pliku JSONL (filtrowania, wzbogacania i zmiany struktury danych) oraz załadowania wyniku do hurtowni danych lub magazynu obiektowego. Każdy etap odczytuje i zapisuje pliki JSONL, dzięki czemu można sprawdzić wyniki pośrednie i niezależnie uruchamiać ponownie poszczególne zadania.

Kompletny DAG w Airflow, który pobiera dane z API, przekształca je w formacie JSONL i ładuje wynik do magazynu danych w chmurze. Zadania wymieniają dane za pośrednictwem plików JSONL we współdzielonym magazynie, co ułatwia debugowanie potoku i ponawianie jego wykonania.

DAG w Airflow: potok ETL oparty na 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):
    """Ekstrahuj dane z API i zapisz JSONL na dysk lokalny."""
    ds = context['ds']  # data wykonania: 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):
    """Odczytaj surowy JSONL, filtruj i wzbogac, zapisz oczyszczony 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):
    """Przeslij oczyszczony JSONL do 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

W przypadku dużych plików JSONL, które nie mieszczą się w pamięci, zastosuj transformację strumieniową przetwarzającą jedną linię naraz. Ten wzorzec zapewnia stałe zużycie pamięci niezależnie od rozmiaru pliku i dobrze sprawdza się w zadaniach Airflow, gdzie zasoby workerów mogą być ograniczone.

Zadanie strumieniowej transformacji JSONL
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:
    """Strumieniowo transformuj plik JSONL za pomoca funkcji zdefiniowanej przez uzytkownika.
    Zwroc None z transform_fn, aby pominac rekord."""
    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


# Uzycie wewnatrz zadania Airflow
def enrich(record):
    if record.get('amount', 0) < 0:
        return None  # pomin nieprawidlowe
    record['currency'] = record.get('currency', 'USD').upper()
    return record


stats = stream_transform(
    '/tmp/raw.jsonl',
    '/tmp/enriched.jsonl',
    transform_fn=enrich,
)
print(f'Przetworzono: {stats}')

Ładowanie JSONL do hurtowni danych

Nowoczesne hurtownie danych mają wbudowaną obsługę wczytywania plików JSONL. Snowflake, BigQuery i Redshift potrafią ładować JSONL bezpośrednio z magazynów danych w chmurze, parsować JSON na bieżąco i zapisywać wyniki w tabelach o określonej strukturze. Eliminuje to pośredni etap konwersji do CSV i pozwala zachować zagnieżdżone typy danych.

Snowflake

COPY INTO

Snowflake wczytuje JSONL poleceniem COPY INTO ze stage’ów korzystających z S3, GCS lub Azure Blob. Użyj opcji FILE_FORMAT z TYPE = 'JSON', aby każda linia była parsowana jako osobny dokument JSON. Kolumny typu VARIANT natywnie przechowują dane częściowo ustrukturyzowane.

BigQuery

Obsługa natywna

BigQuery ładuje pliki JSONL z Google Cloud Storage i automatycznie wykrywa schemat. Polecenie bq load z opcją --source_format=NEWLINE_DELIMITED_JSON natywnie obsługuje JSONL. BigQuery potrafi też automatycznie rozpoznać typy kolumn na podstawie wartości JSON.

Redshift

COPY

Amazon Redshift obsługuje ładowanie JSONL z S3 za pomocą polecenia COPY z opcją FORMAT AS JSON. Możesz wskazać plik JSONPaths, aby zmapować klucze JSON na kolumny tabeli i precyzyjnie sterować procesem ładowania.

Zaladuj plik JSONL ze stagea S3 do tabeli Snowflake. Kazda linia staje sie wierszem z kolumna VARIANT zawierajaca sparsowany JSON. Nastepnie mozesz splaszczyc kolumne VARIANT do typowanych kolumn za pomoca Snowflake SQL.

Snowflake: COPY JSONL z S3
-- Utworz stage wskazujacy na Twoj bucket S3
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);


-- Utworz tabele docelowa
CREATE TABLE IF NOT EXISTS raw_events (
  data VARIANT,
  loaded_at TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP()
);


-- Zaladuj pliki JSONL ze stagea
COPY INTO raw_events (data)
  FROM @etl_stage
  FILE_FORMAT = (TYPE = 'JSON')
  PATTERN = '.*\.jsonl'
  ON_ERROR = 'CONTINUE';


-- Odpytaj zaladowane dane
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;

Uzyj klienta Python BigQuery do zaladowania pliku JSONL z Google Cloud Storage do tabeli BigQuery. Klient obsluguje wykrywanie schematu, partycjonowanie i raportowanie bledow. To podejscie dobrze integruje sie z zadaniami Airflow.

BigQuery: ladowanie JSONL za pomoca klienta 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,
)


# Zaladuj z 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()  # Czekaj na zakonczenie


table = client.get_table(table_ref)
print(f'Zaladowano {load_job.output_rows} wierszy')
print(f'Tabela ma teraz {table.num_rows} wierszy lacznie')

Odporność na awarie i idempotentność

Potoki ETL ulegają awariom. Połączenia sieciowe są zrywane, wywołania API przekraczają limit czasu, a workerom kończy się pamięć. JSONL ułatwia wznowienie pracy, ponieważ każda linia jest niezależna. Możesz zapisać bieżącą pozycję (numer linii) w punkcie kontrolnym, wznowić przetwarzanie od ostatniej poprawnie przetworzonej linii i uniknąć ponownego przetwarzania tych samych danych. W połączeniu z idempotentnym zapisem daje to semantykę przetwarzania dokładnie raz, nawet gdy wiadomości są dostarczane co najmniej raz.

Mechanizm przetwarzania, który zapisuje postęp w punktach kontrolnych na podstawie numeru linii. Po awarii potoku wznawia pracę od ostatniego zatwierdzonego punktu kontrolnego, zamiast przetwarzać cały plik od początku. Punkt kontrolny jest przechowywany w zwykłym pliku tekstowym zawierającym numer ostatniej poprawnie przetworzonej linii.

Przetwarzanie JSONL z punktami kontrolnymi
import json
import os


def get_checkpoint(checkpoint_path: str) -> int:
    """Odczytaj ostatni zatwierdzony numer linii."""
    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):
    """Atomowo zapisz biezacy punkt kontrolny."""
    tmp = checkpoint_path + '.tmp'
    with open(tmp, 'w') as f:
        f.write(str(line_num))
    os.replace(tmp, checkpoint_path)  # atomowe na POSIX


def process_with_checkpoint(
    input_path: str,
    output_path: str,
    checkpoint_path: str,
    batch_size: int = 1000,
):
    """Przetwarzaj plik JSONL z wznawianiem opartym na punktach kontrolnych."""
    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  # pomin juz przetworzone linie
            line = line.strip()
            if not line:
                continue
            record = json.loads(line)
            # --- Twoja logika transformacji ---
            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'Punkt kontrolny w linii {line_num}')


        # Koncowy punkt kontrolny
        save_checkpoint(checkpoint_path, line_num)


    print(f'Gotowe. Przetworzono {processed} rekordow od linii {start_line + 1}')


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

Wzorzec z punktami kontrolnymi sprawdza się na każdym etapie potoku JSONL. W przypadku konsumentów Kafki zastąp punkt kontrolny zapisany w pliku zatwierdzonymi offsetami. W Airflow przechowuj punkt kontrolny w XCom lub zewnętrznej bazie danych, aby ponawiane zadania wznawiały pracę od właściwej pozycji. Najważniejsze jest to, że podział JSONL na linie bardzo upraszcza śledzenie postępu: do wznowienia wystarczy jedna liczba całkowita — numer linii lub offset bajtowy.

Przeglądaj pliki JSONL od razu

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez przesyłania plików na serwer, z zachowaniem 100% prywatności.

Najczęściej zadawane pytania

Źródła