JSONL チュートリアル:ファイルの作成・読み込み・変換
JSONL(JSON Lines)ファイルを扱うために必要な知識を、順を追って解説します。Python、JavaScript、CLI ツールを使ったコード例も紹介します。
JSONL とは?
JSONL(JSON Lines)は、各行に独立した有効な JSON 値を記述する、軽量なテキスト形式です。通常の JSON ではすべてのデータを 単一の配列やオブジェクトにまとめますが、JSONL では 1 行に 1 レコードを格納し、改行文字(\n)で区切ります。
行ごとに独立しているため、大規模なデータセットのストリーミング処理や、ファイル全体を書き直さずにレコードを追記する処理、データの並列処理に適しています。OpenAI のファインチューニング用データセットや、ELK スタックなどのログ管理システム、BigQuery や Apache Spark などのビッグデータツールで広く使われています。
{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Charlie","role":"manager"}JSONL ファイルの作成方法
JSONL ファイルの作成は簡単です。各レコードを 改行を含まない JSON 文字列にシリアライズし、末尾に改行を付けて書き込みます。ここでは、よく使われる言語での実装例を紹介します。
import json
records = [
{"id": 1, "name": "Alice", "role": "engineer"},
{"id": 2, "name": "Bob", "role": "designer"},
{"id": 3, "name": "Charlie", "role": "manager"},
]
with open("output.jsonl", "w", encoding="utf-8") as f:
for record in records:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print("Created output.jsonl with", len(records), "records")import { writeFileSync } from 'fs';
const records = [
{ id: 1, name: 'Alice', role: 'engineer' },
{ id: 2, name: 'Bob', role: 'designer' },
{ id: 3, name: 'Charlie', role: 'manager' },
];
const jsonl = records
.map(record => JSON.stringify(record))
.join('\n');
writeFileSync('output.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created output.jsonl with ${records.length} records`);テキストエディタで手動作成
JSONL ファイルは、どのテキストエディタでも作成できます。1 行に 1 つずつ有効な JSON オブジェクトを記述し、行と行の間にカンマを入れずに、拡張子を .jsonl にして保存します。各行が、それだけで完結した有効な JSON になっていることを確認してください。
JSONL ファイルの読み込み方法
各行が独立した JSON 値なので、JSONL ファイルは 行ごとに順に処理するだけで読み込めます。代表的な方法を紹介します。
import json
with open("data.jsonl", "r", encoding="utf-8") as f:
for line_number, line in enumerate(f, 1):
line = line.strip()
if not line:
continue # skip empty lines
record = json.loads(line)
print(f"Line {line_number}: {record['name']} - {record['role']}")import { createReadStream } from 'fs';
import { createInterface } from 'readline';
const rl = createInterface({
input: createReadStream('data.jsonl', 'utf-8'),
});
let lineNumber = 0;
for await (const line of rl) {
if (!line.trim()) continue; // skip empty lines
lineNumber++;
const record = JSON.parse(line);
console.log(`Line ${lineNumber}: ${record.name} - ${record.role}`);
}# 最初の 10 行を表示
head -n 10 data.jsonl
# 総レコード数をカウント
wc -l data.jsonl
# jq で各行を整形出力
cat data.jsonl | jq .
# role が "engineer" のレコードをフィルター
cat data.jsonl | jq 'select(.role == "engineer")'
# name フィールドのみを抽出
cat data.jsonl | jq -r '.name'
# キーワードを含む行を検索
grep '"Alice"' data.jsonlJSON を JSONL に変換する方法
通常の JSON 配列を JSONL に変換するには、配列の各要素を 行ごとに書き出します。JSONL を扱う際によく行う操作の 1 つです。
import json
# JSON 配列を読み込む
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f) # expects a JSON array
# JSONL として書き出す
with open("data.jsonl", "w", encoding="utf-8") as f:
for record in data:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print(f"Converted {len(data)} records from JSON to JSONL")import { readFileSync, writeFileSync } from 'fs';
// JSON 配列を読み込む
const data = JSON.parse(readFileSync('data.json', 'utf-8'));
// JSONL として書き出す
const jsonl = data
.map(record => JSON.stringify(record))
.join('\n');
writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log(`Converted ${data.length} records from JSON to JSONL`);CSV を JSONL に変換する方法
CSV を JSONL に変換するには、CSV のヘッダーをフィールド名として使い、各行を JSON オブジェクトに変換します。表形式のデータを、ストリーミング処理や機械学習に適した形式へ移行するときに便利です。
import csv
import json
with open("data.csv", "r", encoding="utf-8") as csv_file:
reader = csv.DictReader(csv_file)
with open("data.jsonl", "w", encoding="utf-8") as jsonl_file:
for row in reader:
jsonl_file.write(json.dumps(row, ensure_ascii=False) + "\n")
print("Converted CSV to JSONL successfully")import { readFileSync, writeFileSync } from 'fs';
const csv = readFileSync('data.csv', 'utf-8');
const lines = csv.trim().split('\n');
const headers = lines[0].split(',');
const jsonl = lines.slice(1).map(line => {
const values = line.split(',');
const obj = {};
headers.forEach((h, i) => obj[h.trim()] = values[i]?.trim());
return JSON.stringify(obj);
}).join('\n');
writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log('Converted CSV to JSONL successfully');JSONL のベストプラクティス
JSONL ファイルの文字コードは、すべて UTF-8 にしてください。プラットフォーム間の互換性を確保でき、さまざまな言語の文字を扱えます。
1 行には必ず 1 つの JSON オブジェクトだけを記述してください。オブジェクトを複数行に分けたり、同じ行に複数のオブジェクトを並べたりしないでください。
行と行の間にカンマを入れないでください。JSON 配列とは異なり、JSONL では改行文字だけを区切り文字として使います。
各行を個別に検証してください。すべての行が、それだけで完結した有効な JSON 値である必要があります。JSONL バリデーターを使って、構文エラーを早めに見つけましょう。
大きなファイルはストリーミングで読み込んでください。ファイル全体をメモリに読み込む代わりに、Node.js の readline や Python のファイルに対する反復処理を使い、行ごとに処理します。
レコードの構造を揃えてください。JSONL では行ごとに異なるスキーマを使えますが、構造を統一するとデータ処理が格段に楽になります。
行末に余分な空白を入れないでください。パース時の問題につながる可能性があるため、余分なスペースやタブが入っていないことを確認してください。
ファイルの末尾には改行を入れてください。最後のレコードの後に改行を入れると、wc や cat などのツールでファイルを正しく扱いやすくなります。
JSONL でよくあるエラー
[
{"name":"Alice"},
{"name":"Bob"}
]{"name":"Alice"}
{"name":"Bob"}JSONL は JSON 配列ではありません。全体を角括弧で囲んだり、行と行の間にカンマを入れたりしないでください。各行はそれぞれ独立しています。
{"name":"Alice"},
{"name":"Bob"},{"name":"Alice"}
{"name":"Bob"}JSONL では、各行の末尾や行と行の間にカンマを入れることはできません。区切り文字として使うのは改行文字だけです。
{
"name": "Alice",
"age": 30
}{"name":"Alice","age":30}各 JSON オブジェクトは、必ず 1 行に収めてください。インデントや改行を使って整形した JSON は、有効な JSONL にはなりません。
{"text":"She said "hello""}{"text":"She said \"hello\""}JSON 文字列内の引用符や特殊文字は、バックスラッシュで適切にエスケープする必要があります。引用符をエスケープしないと、JSON のパース時にエラーになります。
JSONL を検証する
JSONL ファイルを作成したら、検証して構文エラーを早めに見つけましょう。無料のバリデーターで、各行をすぐにチェックできます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
JSONL ファイルに適切なインデントを付けて、読みやすく整形できます。デバッグやデータのレビューがしやすくなります。
JSON 配列を JSONL 形式に変換できます。ストリーミングや機械学習向けのデータ準備に適しています。
JSONL データを表計算用の CSV ファイルにエクスポートできます。Excel や Google Sheets での分析に便利です。
Python で JSONL ファイルを扱うための完全ガイドです。json、pandas、orjson を使った読み書きとパース、大容量ファイルのストリーミング処理を解説します。