Python で JSONL を扱う:読み込み・書き込み・解析
Python で JSONL(JSON Lines)ファイルを扱う方法をまとめたガイドです。組み込みモジュールや pandas、高性能なライブラリを使って、JSONL データの読み込み、書き込み、解析、ストリーミング処理を行う方法を解説します。
JSONL の処理に Python が選ばれる理由
Python は JSONL ファイルの処理に最もよく使われる言語であり、それには理由があります。組み込みの json モジュールですぐに JSON を解析でき、ファイルを順に読み込むだけでメモリを効率よく使えます。また、用途に応じて pandas や orjson などの強力なライブラリも利用できます。機械学習のデータセット、アプリケーションログ、API レスポンスなど、どのようなデータでも、Python なら JSONL を手軽に扱えます。
JSONL(JSON Lines)は、1行に1つの JSON オブジェクトを格納する形式です。ストリーミング処理やログの追記に適しており、大規模なデータセットも全体をメモリに読み込まずに処理できます。Python のファイルを1行ずつ読み込む仕組みは、この形式と相性がよいものです。このガイドでは、JSONL を読み込む3つの方法と書き込む2つの方法に加え、メモリに収まらないファイルの処理方法を紹介します。
Python で JSONL ファイルを読み込む
Python で JSONL ファイルを読み込む方法は複数あり、用途に応じて使い分けられます。たいていの処理には標準の json モジュールで対応できます。表形式のデータを分析するなら pandas が便利で、大容量ファイルにはジェネレーターが適しています。
最もシンプルなのは、Python 組み込みの json モジュールを使う方法です。ファイルを開いて1行ずつ読み込み、各行を json.loads() で解析します。この方法では、すべてのレコードをメモリ上のリストに格納します。
import json
records = []
with open('data.jsonl', 'r', encoding='utf-8') as f:
for line in f:
line = line.strip()
if line: # Skip empty lines
records.append(json.loads(line))
print(f'Loaded {len(records)} records')
print(records[0])JSONL データが表形式で、すべてのレコードに同じキーがある場合は、pandas の関数を1回呼び出すだけで DataFrame に直接読み込めます。構造化された JSONL データの分析をすぐに始められる方法です。
import pandas as pd
# Read entire file into a DataFrame
df = pd.read_json('data.jsonl', lines=True)
print(df.head())
print(f'Shape: {df.shape}')
# For large files, read in chunks
chunks = pd.read_json('large.jsonl', lines=True, chunksize=10000)
for chunk in chunks:
# Process each chunk (DataFrame)
print(f'Chunk shape: {chunk.shape}')メモリに収まらない大容量ファイルには、ジェネレーター関数を使います。1レコードずつ返すため、ファイルサイズにかかわらずメモリ使用量を一定に保てます。本番環境のデータパイプラインで推奨される方法です。
import json
from typing import Iterator, Any
def read_jsonl(path: str) -> Iterator[dict[str, Any]]:
"""Read a JSONL file lazily, yielding one record at a time."""
with open(path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
try:
yield json.loads(line)
except json.JSONDecodeError as e:
print(f'Skipping invalid JSON at line {line_num}: {e}')
# Process records one at a time
for record in read_jsonl('large_data.jsonl'):
process(record) # Only one record in memory at a timePython で JSONL ファイルを書き込む
JSONL ファイルへの書き込みはシンプルです。各レコードを JSON 文字列にシリアライズし、その後ろに改行文字を付けます。1行に1つの JSON オブジェクトを記述し、末尾にカンマを付けたり、全体を配列で囲んだりしないことが基本ルールです。
json.dumps() で各レコードをシリアライズし、その後ろに改行を付けて書き込みます。ensure_ascii=False を指定すると、中国語や日本語、絵文字などの Unicode 文字をそのまま出力できます。
import json
records = [
{"id": 1, "name": "Alice", "age": 30},
{"id": 2, "name": "Bob", "age": 25},
{"id": 3, "name": "Charlie", "age": 35},
]
with open('output.jsonl', 'w', encoding='utf-8') as f:
for record in records:
f.write(json.dumps(record, ensure_ascii=False) + '\n')
print(f'Wrote {len(records)} records to output.jsonl')データがすでに pandas の DataFrame に入っている場合は、to_json() に orient='records' と lines=True を指定すると、JSONL として直接出力できます。これは、pd.read_json() に lines=True を指定して読み込む操作の逆にあたります。
import pandas as pd
df = pd.DataFrame([
{"id": 1, "name": "Alice", "age": 30},
{"id": 2, "name": "Bob", "age": 25},
{"id": 3, "name": "Charlie", "age": 35},
])
# Write DataFrame to JSONL
df.to_json('output.jsonl', orient='records', lines=True, force_ascii=False)
print(f'Wrote {len(df)} records to output.jsonl')JSONL を扱う Python ライブラリ
Python には JSON を解析するライブラリが複数あり、それぞれ性能に特徴があります。ファイルサイズや必要な処理速度に応じて選びましょう。
json(標準ライブラリ)
組み込みPython 組み込みの json モジュールは、追加のインストールなしで、どの環境でも使えます。JSONL を扱うほとんどの処理に対応でき、標準の JSON のデータ型をすべてサポートしています。数百 MB までのファイルであれば、十分な性能を備えています。
orjson
最速orjson は、Rust で書かれた最速の Python 向け JSON ライブラリです。標準の json モジュールに比べ、解析とシリアライズが2〜10倍高速です。文字列ではなくバイト列を出力し、dataclass、datetime、numpy、UUID 型に標準で対応しています。
ujson
高速ujson(UltraJSON)は C で実装された JSON ライブラリで、標準の json モジュールより2〜5倍高速です。API が組み込みの json モジュールとほぼ同じなので、そのまま置き換えて使えます。互換性と速度のバランスを取りたい場合に適しています。
大容量 JSONL ファイルをストリーミング処理する
ギガバイト規模の JSONL ファイルを扱うには、データをバッチ単位で読み込み、変換して書き出すストリーミング処理が必要です。この方法なら、メモリ使用量を一定に保ちながら、処理の進捗も確認できます。
import json
import sys
def process_large_jsonl(
input_path: str,
output_path: str,
batch_size: int = 1000
) -> int:
"""Stream-process a large JSONL file in batches."""
processed = 0
batch: list[dict] = []
with open(input_path, 'r') as fin, \
open(output_path, 'w') as fout:
for line in fin:
line = line.strip()
if not line:
continue
record = json.loads(line)
# Transform the record
record['processed'] = True
batch.append(record)
if len(batch) >= batch_size:
for r in batch:
fout.write(json.dumps(r) + '\n')
processed += len(batch)
batch.clear()
print(f'\rProcessed {processed} records...', end='')
# Write remaining records
for r in batch:
fout.write(json.dumps(r) + '\n')
processed += len(batch)
print(f'\nDone. Processed {processed} records total.')
return processed
# Usage
process_large_jsonl('input.jsonl', 'output.jsonl', batch_size=5000)この方法では、一定件数のレコードをバッチにまとめて処理することで、メモリ使用量を一定に保ちます。batch_size パラメータで、メモリ使用量と I/O 効率のバランスを調整できます。多くのシステムでは、バッチあたり1,000〜10,000 レコードが適切です。進捗表示があるため、長時間かかるジョブの処理状況も確認できます。
無料の JSONL ツールを試す
コードを書かずに JSONL を扱いたい場合は、無料のオンラインツールをご利用ください。ブラウザ上で直接、JSONL ファイルの表示、検証、変換ができます。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
整形、スキーマの一貫性、エラーハンドリング、パフォーマンスの最適化、ファイル整理に関する JSONL のベストプラクティスを解説します。実践的な例を通じて、よくある落とし穴を避ける方法を学べます。
JSONL ファイルを標準的な JSON 配列に変換できます。API やデータ処理パイプラインでの利用に適しています。
JavaScript と Node.js で JSONL ファイルを扱うための完全ガイドです。実践的な例を通じて、JSONL データの読み書き、パース、ストリーミング処理を学べます。