- Strona główna
- Przewodnik
- JSONL w potokach ETL: Kafka, Airflow i hurtownie danych
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().
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.
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.
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_loadW 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.
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 INTOSnowflake 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 natywnaBigQuery ł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
COPYAmazon 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.
-- 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.
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.
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.
Sprawdź poprawność JSONL przed załadowaniem
Wykryj nieprawidłowe rekordy, zanim trafią do potoku. Skorzystaj z naszych bezpłatnych narzędzi online do walidacji, przeglądania i konwersji plików JSONL w przeglądarce.
Dowiedz się, jak strumieniować dane JSONL w Node.js i Pythonie. Obejmuje SSE, WebSockets i przetwarzanie logów w czasie rzeczywistym.
Dowiedz się, jak importować i eksportować dane JSONL z baz danych PostgreSQL, MongoDB, MySQL i SQLite.
Dowiedz się, jak walidować pliki JSONL przy użyciu JSON Schema. Obejmuje Python, Node.js, narzędzia CLI i automatyzację CI/CD.
Sposoby przetwarzania gigabajtów danych JSONL: odczyt strumieniowy, zarządzanie pamięcią, dzielenie plików, kompresja i narzędzia online.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.