著者: Jerry Fan

大容量 JSONL ファイル(1GB+)を扱うには

ギガバイト規模の JSONL データを効率よく処理するための方法とベストプラクティス

大容量の JSONL ファイルに工夫が必要な理由

JSONL ファイル全体を Python の辞書や JavaScript のオブジェクトとしてパースすると、ディスク上のファイルサイズよりも大幅に多くのメモリが必要になることがあります。追加のメモリ使用量は、レコード数、フィールド名、値、ランタイムによって変わります。ファイルサイズの一定の倍数になると決めつけず、代表的なファイルで測定してください。

JSONL の大きな利点は、通常の JSON と異なり、1行ずつ処理できることです。各行が独立した JSON ドキュメントなので、ファイル全体を読み込む必要がありません。このようにストリーミング処理ができるため、機械学習、ログ分析、データエンジニアリングで大規模なデータセットを扱う際には、JSONL がよく使われます。

ストリーミングで読み込む方法

大容量の JSONL ファイルを扱う基本は、1行ずつ読み込み、レコードごとに処理することです。ここでは、よく使われる言語やツールでの実装例を紹介します。

Python のファイルの反復処理では、1 行ずつ読み込みます。メモリ使用量は最大の行と、処理コードが保持するデータに左右されます。非常に大きなレコードであれば、1 件だけでもメモリを使い切る可能性があります。

Python
import json


def process_large_jsonl(filepath: str) -> int:
    """Process a large JSONL file line by line."""
    count = 0
    errors = 0
    
    with open(filepath, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                record = json.loads(line)
                # Process your record here
                count += 1
            except json.JSONDecodeError as e:
                errors += 1
                print(f'Line {line_num}: {e}')
    
    print(f'Processed {count} records, {errors} errors')
    return count

Node.js の readline インターフェースを使うと、ストリームを通じてファイルを1行ずつ効率よく処理できます。数ギガバイトのファイルでも、メモリ使用量を最小限に抑えられます。

Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


async function processLargeJsonl(filepath) {
  const rl = createInterface({
    input: createReadStream(filepath, 'utf-8'),
    crlfDelay: Infinity,
  });


  let count = 0;
  for await (const line of rl) {
    const trimmed = line.trim();
    if (!trimmed) continue;
    try {
      const record = JSON.parse(trimmed);
      // Process your record here
      count++;
    } catch (err) {
      console.error(`Parse error: ${err.message}`);
    }
  }
  console.log(`Processed ${count} records`);
}

Unix のコマンドラインツールは、コードを書かずに大容量の JSONL ファイルを手早く確認したり、処理したりするのに最適です。

コマンドラインツール
# Count lines in a JSONL file
wc -l data.jsonl


# View first 10 records
head -n 10 data.jsonl


# View last 5 records
tail -n 5 data.jsonl


# Pretty-print first record
head -n 1 data.jsonl | jq .


# Filter records with jq
jq -c 'select(.age > 30)' data.jsonl


# Extract specific fields
jq -c '{name, email}' data.jsonl

メモリ管理の工夫

1行ずつ読み込むという基本に加えて、次の方法を取り入れると、大容量の JSONL ファイルをさらに効率よく処理できます。

レコードを 1,000〜10,000 件ずつのバッチにまとめて処理すると、メモリ使用量と処理効率のバランスを取れます。特に、データベースへの書き込みや API 呼び出しを行う場合に有効です。

バッチ処理
import json
from typing import Iterator


def read_jsonl_batches(
    filepath: str,
    batch_size: int = 5000
) -> Iterator[list]:
    batch = []
    with open(filepath, 'r') as f:
        for line in f:
            record = json.loads(line.strip())
            batch.append(record)
            if len(batch) >= batch_size:
                yield batch
                batch = []
    if batch:
        yield batch


# Usage
for batch in read_jsonl_batches('large.jsonl'):
    # Insert batch into database
    db.insert_many(batch)

処理中のメモリ使用量を監視することで、問題を早期に見つけ、バッチサイズを調整できます。

メモリ使用量の監視
import json
import psutil
import os


def process_with_monitoring(filepath: str):
    process = psutil.Process(os.getpid())
    
    with open(filepath, 'r') as f:
        for i, line in enumerate(f):
            record = json.loads(line)
            # Process record
            
            if i % 100000 == 0:
                mem = process.memory_info().rss / 1024 / 1024
                print(f'Line {i:,}: {mem:.1f} MB')

大容量 JSONL ファイルの分割

並列処理を行う場合や、サイズ制限のあるサービスにアップロードする場合、複数のマシンに処理を分散する場合には、大容量の JSONL ファイルを小さなファイルに分割する必要があることもあります。

行を途中で切らずに分割するには split -l を使用します。単独で使える JSONL ファイルに分割する場合は、split -b を使用しないでください。バイト単位の区切り位置で、JSON レコードや UTF-8 文字が途中で切れるおそれがあります。以下のコマンドは新しいディレクトリを作成し、同名のディレクトリがすでに存在する場合は停止します。

split コマンドを使う
# Split into parts of 100,000 complete lines in a NEW directory
mkdir jsonl-parts &&
split -l 100000 data.jsonl jsonl-parts/chunk_ &&
for f in jsonl-parts/chunk_*; do
    [ -f "$f" ] || continue
    mv "$f" "$f.jsonl"
done

こちらの Python の例は行数で分割し、UTF-8 文字や改行文字を含む入力のバイト列をそのまま保持します。新しい出力ディレクトリを作成し、既存のディレクトリは上書きしません。分割しても無効なレコードは修復されないため、先に入力を検証してください。

Python スクリプト
from pathlib import Path


def split_jsonl(input_path, output_dir="jsonl-parts", lines_per_file=100000):
    if lines_per_file < 1:
        raise ValueError("lines_per_file must be positive")
    directory = Path(output_dir)
    file_num = 0
    output = None
    with open(input_path, "rb") as source:
        directory.mkdir()  # Refuse to overwrite an existing directory
        try:
            for line_number, line in enumerate(source):
                if line_number % lines_per_file == 0:
                    if output is not None:
                        output.close()
                    file_num += 1
                    output = (directory / f"part_{file_num:04d}.jsonl").open("xb")
                output.write(line)
        finally:
            if output is not None:
                output.close()
    print(f"Split into {file_num} files")


split_jsonl("data.jsonl")

圧縮の活用

レコード内で同じフィールド名や値が繰り返される場合、JSONL は圧縮によってサイズを小さくできることがよくあります。削減量はデータセット、圧縮レベル、コーデックによって変わります。代表的なサンプルで、圧縮後のサイズと処理時間を測定してください。

Python の gzip モジュールを使うと、圧縮を意識せずに JSONL ファイルを扱えます。圧縮ファイルには慣例として .gz 拡張子が使われ、ツールが自動的に認識します。

gzip 圧縮した JSONL の読み書き
import gzip
import json


# Reading gzipped JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        # Process record


# Writing gzipped JSONL
with gzip.open('output.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record) + '\n')

圧縮方式の比較

互換性と、ご自身のデータで測定した性能に基づいてコーデックを選んでください。以下は選択時に考慮する特徴であり、ベンチマーク結果ではありません。

gzip:幅広くサポートされており、圧縮した JSONL の受け渡しに実用的な選択肢です。

zstd:圧縮レベルを調整できます。実際のワークロードで、サイズとスループットを gzip と比較してください。

lz4:高速な圧縮と展開を目的として設計されています。ご自身のデータで、速度とサイズの兼ね合いを測定してください。

圧縮なし:展開処理は不要ですが、より多くのストレージを使用します。バイト単位で直接アクセスする必要がある場合に便利です。

ブラウザで大容量ファイルを処理する

jsonl.co は、ブラウザ内で JSONL ファイルをローカルに読み込みます。ビューアはファイルをチャンク単位で走査し、仮想スクロールを使うため、すべてのレコードを一度に描画しません。ファイルの内容はアップロードされません。

扱えるファイルサイズは、ブラウザのメモリ、デバイスのリソース、レコードサイズ、実行する操作によって変わります。入力をストリームとして読み込んでも、出力に必要なメモリが一定の範囲に収まるとは限りません。たとえば Excel 変換では、行データを蓄積し、メモリ内でブックを作成します。まず小さなサンプルで試し、必要に応じてファイルを分割してください。

大容量の JSONL ファイルをオンラインで処理する

ブラウザのビューアで JSONL をローカルに確認できます。データ量が多い場合は、ファイルを分割するか、上記の 1 行ずつ処理するスクリプトを使用してください。

よくある質問

参考資料