JSONLファイルをマスターする：構造、ユースケース、主なメリット

JSONLファイルは、1行に1つの完全なJSON値を保持します。公式ドキュメントでは、これを「JSON Linesテキストフォーマット、または改行区切りJSON」と呼んでいます。このシンプルなルールこそが、ストリーミング処理に適し、部分的な読み込みでも破損せず、スプレッドシートでは開けない理由です。

JSONLファイルとは？

JSON Linesは、レコード用のテキストフォーマットです。仕様書では、「1回に1レコードずつ処理される可能性のある構造化データを保存するための便利なフォーマット」と説明されています。

ドキュメントでは、その用途が明確に示されています。これは「Unixスタイルのテキスト処理ツールやシェルパイプラインと相性が良い」とされており、さらに「ログファイルに最適なフォーマットである」とも付け加えられています。また、「連携するプロセス間でメッセージを渡すための柔軟なフォーマット」とも説明されています。

通常のJSONとの対比が重要なポイントです。100万件のレコードを含むJSON配列は1つの値であり、読み手は構造が完了する前に全体を読み込む必要があります。一方、100万件のレコードを含むJSONLファイルは100万個の値であり、各行が独立しています。

密接に関連するもう1つの仕様があります。NDJSONの仕様書には、「現在、ストリームプロトコル内でJSONテキストのインスタンスを転送するための標準は存在しない」と率直に書かれています。その想定されるユースケースは、「TCPやUNIXパイプなどのストリーミングプロトコルを介して、複数のJSONテキストのインスタンスを配信すること」です。

JSONLファイルの構造

3つの要件

JSON Linesのドキュメントには、正確に3つの要件が挙げられています。1つ目はUTF-8エンコーディングです。これには、JSON自体から借用された「JSON標準と同様に、バイトオーダーマーク（U+FEFF）を含めてはならない」という警告が伴います。

2つ目は、各行が有効なJSON値であることです。ページには「最も一般的な値はオブジェクトまたは配列ですが、任意のJSON値が許可されます」と記載されています。そして、人々がつまずきやすいエッジケースとして「nullは有効な値ですが、空行は無効です」と説明されています。

3つ目は、行末記号が\nであることです。Windowsの改行コードも機能します。その理由は機械的なもので、「JSON値を解析する際、周囲の空白は暗黙的に無視されるため、\r\nもサポートされることを意味します」と説明されています。

行内に含めてはならないもの

これが、このフォーマットを機能させる制約です。NDJSONの仕様書では、要件として「JSONテキストには改行やキャリッジリターンを含めてはならない」と規定されています。

通常、JSON値はインデントを伴って複数行にまたがることが許可されています。しかし、行区切りのファイルでは、改行がレコードの区切り文字となるため、それは不可能です。すべてのレコードは、物理的な1行に記述される必要があります。

最終行と空行

2つの仕様の間で異なる詳細が2点あり、どちらもファイルが拒否された場合に重要となります。

末尾の改行を例にとってみましょう。JSON Linesでは、「ファイル内の最後のJSON値の後に行末記号を含めることは強く推奨されますが、必須ではありません」とされています。

空行については、2つの仕様で意見が分かれています。JSON Linesは厳格で、空行は有効な値ではありません。一方、NDJSONは寛容であり、「パーサーは空行を暗黙的に無視してもよい」としつつ、「この動作は文書化されなければならない」と要求しています。

拡張子とメディアタイプ

命名についても分かれています。JSON Linesでは、ファイルは「ファイル拡張子.jsonlで保存される場合があります」とされています。メディアタイプについては、「MIMEタイプはapplication/jsonlである可能性がありますが、これはまだ標準化されていません」と述べられています。NDJSONでは、メディアタイプは「application/x-ndjsonであるべき」であり、拡張子は「.ndjsonであるべき」とされています。

圧縮について、JSON Linesはストリーム圧縮を推奨しています。「スペースを節約するためにgzipまたはbzip2が推奨され、結果として.jsonl.gzまたは.jsonl.bz2ファイルになります。」

エラーメッセージを読む際に知っておくと便利な、ちょっとした慣例があります。テキストエディタは最初の行を「1行目」と呼びます。ドキュメントはこれを拡張し、「JSON Linesファイル内の最初の値も『値1』と呼ばれるべきです」としています。

JSONLの用途

通常、.jsonlファイルには以下の4つの状況のいずれかで遭遇します。

ログおよびイベントファイル。 このフォーマット自体のドキュメントでもログファイルが挙げられており、その理由は、書き込み側が何も書き換えることなく、一度に1行ずつ追記できるためです。

ウェアハウスへのロード。 GoogleのBigQueryのドキュメントは、このフォーマットの公式な地位を示す良い例です。Cloud Storageからの「改行区切りJSON（ndJSON）データのロード」をサポートしており、そのファイル形式選択ツールでは、このオプションが「JSONL（改行区切りJSON）」としてリストされています。

ネストされたレコードのAPIエクスポート。 列にきれいにフラット化できないデータは、行ごとにネスト構造を維持します。項目数が変動する注文明細などが、その典型的な例です。

機械学習のデータセット。 トレーニングループはレコードを1つずつ読み込むため、トレーニングセットや評価セットは一般的にこの方法で配布されます。

共通しているのは「ストリーミング」です。ファイルが段階的に生成される場合、または段階的に消費される場合、これが明らかな選択肢となります。

JSONL、JSON、CSVの比較

	JSONL	JSON	CSV
ファイルの単位	1行に1つの値	ファイル全体で1つの値	1行に1行
ネストされたデータ	はい（レコードごと）	はい	ネイティブでは非対応
レコードの追記	行を追加	コンテナ全体を書き換え	行を追加
部分的な読み込みの有用性	はい	ほとんどない	はい
スプレッドシートで開けるか	いいえ	いいえ	通常は可能
レコードごとに形状が異なってもよいか	はい	はい	いいえ（列は固定）
エディタでの可読性	はい（それぞれ1つの長い行として表示）	はい（インデントされている場合）	はい

最も驚かれるのは、下から2番目の行です。同じJSONLファイル内の2つの行が、異なるキーを持つことができます。これこそがこのフォーマットに柔軟性をもたらす理由であり、同時に、単純にインポートすると列が不揃いになってしまう原因でもあります。

列指向のバイナリ代替案については、Parquetの解説記事がストレージの観点から同じ領域をカバーしています。最もシンプルな表形式のケースについては、TSVの解説記事がタブ区切りテキストについて説明しています。

主なメリット

追記専用の書き込み。 新しいレコードは新しい行になります。ファイル内のそれ以前の部分を変更する必要はありません。

ストリーミング読み込み。 200万番目のレコードが書き込まれる前に、コンシューマーは最初のレコードを処理できます。

障害耐性。 途中で切断されたファイルであっても、最後の完全な行までは読み込むことができます。途中で切断されたJSON配列は、通常、全体が読み込めなくなります。

ネスト構造の維持。 CSVではフラット化しなければならない構造が、各レコードの内部でそのまま維持されます。

シェルとの親和性。 ドキュメントではUnixスタイルのテキスト処理やシェルパイプラインが挙げられていますが、これは行指向のファイルが行指向のツールで動作するためです。

ウェアハウスのサポート。 BigQueryのドキュメントには、適用されるルールとして「各JSONオブジェクトは、ファイル内の個別の行に存在する必要があります」と記載されています。

JSONLが万能ではない点

このフォーマットは転送と追記の問題を解決します。しかし、コンテンツに関する疑問を解決するものではありません。

圧縮は、無条件のメリットではなく、現実的なトレードオフです。BigQueryのドキュメントには、そのコストについて「gzip圧縮を使用する場合、BigQueryはデータを並列に読み取ることができません」と率直に書かれています。さらに、「圧縮されたJSONデータをBigQueryにロードするのは、圧縮されていないデータをロードするよりも遅くなります」とも付け加えられています。一方で、このフォーマット自体のページでは、スペースを節約するためにgzipが推奨されています。どちらも真実であり、相反する方向を向いています。

また、冗長でもあります。すべての行で各キー名が繰り返されるため、レコードの項目数が多い場合、列指向フォーマットの同じデータよりも大幅にサイズが大きくなります。

そして、一貫性については何も保証しません。異なる形状のレコードが許可されているため、ファイルの中盤で特定のフィールドが静かに表示されなくなっても、エラーにはなりません。

エンジニアではない人がJSONLファイルを扱う方法

ここに実務上のギャップがあります。ビジネスツールは行と列を想定しているため、.jsonlファイルはCSVのように簡単には開けません。

現実的なアプローチは、変換ステップを挟むことです。ファイルを生成した担当者に、必要なフィールドをフラット化したCSVまたはExcelの抽出データを依頼してください。あるいは、JSONに対応したツールを使って自分でフラット化します。ネスト構造は失われますが、分析に使用するフィールドが決まってしまえば、通常は問題ありません。

そこから先は通常の分析作業です。Powerdrill Bloomの料金ページには、Excel、CSV、PDF、およびドキュメントのアップロードがリストされているため、フラット化した抽出データをそのまま投入できます。クエリを作成する代わりに、自然言語で質問を投げかけることができます。CSV AI assistantがそのプロセスをサポートし、データをエクスポートするよりもソースから直接取得した方がよい場合は、data connectorsが対応します。

覚えておくべき重要な違いは、これがあなたの手元に届くより上流で決定された転送用の仕様であるということです。ファイルがデスクに届いた後に別の形式に変換することは、一時しのぎの回避策ではなく、ごく通常のプロセスです。

まとめ

JSONLは、「1行に1つの完全なJSON値、値の内部に改行は含めない」という1つのルールを持つテキストフォーマットです。このルールによって、追記性、ストリーミング、部分読み込みへの耐性が得られるため、ログやウェアハウスへのロードでデフォルトとして採用されています。

一方で、テーブルとしての利便性は得られません。パイプラインではなく「答え」を必要とする人の手元にファイルが届いた瞬間、次に取るべき有用なステップは、フラット化した抽出データを作成し、問いを投げかけることです。

もしそのような状況にあるなら、変換したファイルを使ってPowerdrill Bloomをお試しいただき、まずはチャートへの変換から始めてみてください。

よくある質問

JSONLファイルは何に使われますか？

ログファイル、イベントのエクスポート、ウェアハウスへのロード、機械学習のデータセットなど、レコードのストリームに使用されます。このフォーマットのドキュメントでは、特にログファイルやシェルパイプラインが挙げられています。共通しているのは、レコードが一度に1つずつ書き込まれる、または読み込まれる点です。

JSONLとNDJSONの違いは何ですか？

これらは同じ概念を異なる仕様書で説明したものです。JSON Linesは拡張子.jsonlを使用し、application/jsonlはまだ標準化されていないと指摘しています。一方、NDJSONは.ndjsonとapplication/x-ndjsonを指定し、パーサーが空行を無視することを許可しています。

ExcelでJSONLファイルを開くことはできますか？

ダブルクリックして開くことはできません。各行がセルの行ではなくJSON値であるためです。一般的なアプローチは、まず必要なフィールドをCSVまたはExcelにフラット化するか、このフォーマットを直接読み込めるツールを使用することです。

なぜJSONLではレコードを複数行にまたがって記述できないのですか？

改行文字がレコードの区切り文字だからです。NDJSONの仕様書では、「JSONテキストには改行やキャリッジリターンを含めてはならない」と規定されています。そのため、整形されたJSONは、レコードごとに1行に折りたたむ必要があります。

JSONLファイルで空行は許可されていますか？

2つの仕様で異なります。JSON Linesでは「nullは有効な値ですが、空行は無効です」とされています。NDJSONでは、その動作が文書化されていることを条件に、パーサーが空行を暗黙的に無視することを許可しています。