ETL パイプラインで JSONL を活用する:Kafka、Airflow、データウェアハウス
現代の ETL パイプラインで、JSONL(JSON Lines)をデータ交換形式として活用するための実践ガイドです。Kafka で JSONL イベントを送受信する方法、Airflow DAG で JSONL の変換処理を連携させる方法、Snowflake、BigQuery、Redshift に JSONL データをロードする方法を解説します。
JSONL が ETL のデータ交換形式に最適な理由
Extract-Transform-Load(ETL)パイプラインは、システム間でデータを移動させますが、システム同士で同じスキーマを使っていることはほとんどありません。JSONL は各行が独立した JSON ドキュメントになっているため、この用途に特に適しています。ヘッダーを失う心配も、区切り文字をエスケープする手間もなく、一部の処理が失敗しても、複数行にまたがるレコードを組み立て直す必要がありません。各行を個別に検証・変換し、振り分け先を決められる点は、Kafka や Airflow のような分散システムにまさに求められる特性です。
JSONL は CSV と異なり、ネストした構造や配列、値の型を曖昧さなく保持できます。また、Parquet や Avro と異なり、人がそのまま読めるため、内容の確認に専用ツールは必要ありません。このため、JSONL はパイプラインの各ステージをつなぐデータ形式として適しています。Kafka のトピックでは JSONL メッセージをやり取りし、Airflow のタスクではオブジェクトストレージ上の JSONL ファイルを読み書きし、データウェアハウスでは標準の一括ロードコマンドで JSONL を取り込めます。このガイドでは、各ステージで使える具体的な実装パターンを、本番環境向けのコードとともに紹介します。
Kafka + JSONL:イベントストリーミング
Apache Kafka はリアルタイム ETL を支える基盤です。プロデューサーはイベントを JSONL 形式のメッセージとして送信し、コンシューマーはそれを行単位で読み取って下流のシステムに取り込みます。Kafka メッセージ1つに1つの JSON オブジェクトを格納するため、各メッセージが単一の JSONL レコードに対応します。この形式は、ログを基盤とする Kafka のアーキテクチャによく適合します。シリアライズも簡単で、コンシューマーはバッファリングせずに各メッセージを個別にパースできます。
Python の辞書をシリアライズし、JSONL 形式のメッセージとして送信する Kafka プロデューサーの例です。各メッセージは単一の JSON 行 として Kafka トピックに送信されます。value_serializer がエンコードを自動で処理するため、send() メソッドには dict を渡すだけで済みます。
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')JSONL メッセージを読み取り、ローカルの JSONL ファイルにバッチ単位で書き込む Kafka コンシューマーの例です。まとめて書き込むことで I/O のオーバーヘッドを抑え、下流のシステムでも大きな単位でデータを処理できます。バッチ全体の書き込みが完了してからオフセットをコミットすることで、少なくとも一度の配信を保証します。
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:JSONL タスクのオーケストレーション
Apache Airflow は、バッチ ETL で標準的に使われるオーケストレーションツールです。JSONL を使う一般的な Airflow パイプラインは、3つのステージで構成されます。まず生データを抽出して JSONL に書き出し、次に JSONL ファイルを変換して、フィルタリング、情報の付加、構造の整形を行います。最後に、結果をデータウェアハウスやオブジェクトストアにロードします。各ステージで JSONL ファイルを読み書きするため、処理途中の状態を確認でき、タスクを個別に再実行できます。
API からデータを抽出し、JSONL 形式で変換処理を行い、結果をクラウドストレージにロードする、一連の処理を実装した Airflow DAG です。各タスクは共有ストレージ上の 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メモリに収まらない大容量の JSONL ファイルには、1行ずつ処理するストリーミング変換を使います。この方法なら、ファイルサイズにかかわらずメモリ使用量を一定に保てます。ワーカーのリソースが限られる Airflow タスクにも適しています。
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}')JSONL をデータウェアハウスにロードする
現在の主要なデータウェアハウスは、JSONL ファイルの取り込みを標準でサポートしています。Snowflake、BigQuery、Redshift はいずれも、クラウドストレージから JSONL を直接ロードし、取り込み時に JSON をパースして、結果を構造化されたテーブルに格納できます。途中で CSV に変換する必要がなく、ネストしたデータ型も保持できます。
Snowflake
COPY INTOSnowflake では、COPY INTO コマンドを使って S3、GCS、Azure Blob のステージから JSONL を取り込みます。FILE_FORMAT オプションに TYPE = 'JSON' を指定すると、各行が独立した JSON ドキュメントとしてパースされます。VARIANT 型の列には、半構造化データをそのまま格納できます。
BigQuery
標準対応BigQuery では、スキーマを自動検出しながら Google Cloud Storage から JSONL ファイルをロードできます。bq load コマンドに --source_format=NEWLINE_DELIMITED_JSON を指定すると、JSONL をそのまま取り込めます。JSON の値から列の型を自動検出することもできます。
Redshift
COPYAmazon Redshift では、COPY コマンドに FORMAT AS JSON を指定して、S3 から JSONL をロードできます。JSONPaths ファイルで JSON のキーとテーブルの列の対応を指定すれば、ロード処理を細かく制御できます。
S3 ステージから Snowflake テーブルに JSONL ファイルをロードします。各行はパースされた JSON を含む VARIANT 列を持つ行になります。その後、Snowflake SQL を使用して VARIANT 列を型付き列にフラット化できます。
-- 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;BigQuery Python クライアントを使用して Google Cloud Storage から BigQuery テーブルに JSONL ファイルをロードします。クライアントがスキーマ検出、パーティショニング、エラーレポートを処理します。このアプローチは 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')耐障害性と冪等性
ETL パイプラインには、ネットワークの切断、API のタイムアウト、ワーカーのメモリ不足といった障害がつきものです。JSONL は各行が独立しているため、障害からの復旧も容易です。処理位置(行番号)をチェックポイントとして記録しておけば、最後に処理が成功した行から再開でき、処理済みのデータを再処理せずに済みます。さらに冪等な書き込みと組み合わせることで、少なくとも一度の配信であっても、処理結果としては正確に一度だけ反映されるセマンティクスを実現できます。
行番号をチェックポイントとして記録し、処理の進捗を管理する実装例です。パイプラインで障害が発生しても、ファイル全体を処理し直さずに、最後にコミットしたチェックポイントから再開できます。チェックポイントファイルは、最後に正常に処理した行番号だけを保存するシンプルなテキストファイルです。
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,
)チェックポイントを使う方法は、JSONL パイプラインのどのステージにも適用できます。Kafka コンシューマーでは、ファイルのチェックポイントの代わりに、コミット済みのオフセットを使います。Airflow では、リトライ時に正しい位置から再開できるよう、チェックポイントを XCom や外部データベースに保存します。ポイントは、JSONL が行単位の形式なので、処理位置を簡単に管理できることです。再開に必要なのは、行番号やバイトオフセットを表す整数一つだけです。
ロード前に JSONL を検証する
形式が不正なレコードを、パイプラインに取り込む前に見つけましょう。無料のオンラインツールを使えば、ブラウザ上で JSONL ファイルを検証・表示・変換できます。
Node.jsとPythonでJSONLデータをストリーミングする方法を学びます。SSE、WebSocket、リアルタイムログ処理をカバー。
PostgreSQL、MongoDB、MySQL、SQLiteデータベースでJSONLデータをインポート・エクスポートする方法を学びます。
JSON Schemaを使用してJSONLファイルを検証する方法を学びます。Python、Node.js、CLIツール、CI/CD自動化をカバー。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。