NDJSON を JSON に変換

JSON 文書は 1 つの値です。NDJSON ファイルは、間に改行を挟んだ値の連続で、どんな好意的な解釈をしても文書にはなりません。パーサーは最初のオブジェクトを読み、2 つ目の開き波括弧に到達して、その位置で予期しないトークンのエラーとともに止まります。これはパーサーの不具合ではなく、このページが存在する理由です。

その帰結はごく普通の場所で表れます。JSON Schema のバリデーターがファイルを拒否します。ブラウザーの response.json() は例外を投げます。import data from "./records.json" はビルド時に失敗します。設定の読み込みツールは、実際には何の問題もない 2 行目に構文エラーを報告します。どの場合も直し方は同じ、1 行分の構造です。全体を角括弧で囲み、各レコードの間にカンマを入れることです。

すべての行は、ファイル内の順序どおりに、トップレベルの配列の 1 要素になります。これは元データが 1 行しかない場合でも変わりません。1 レコードのファイルは、素のオブジェクトではなく 1 要素の配列になります。出力は階層ごとに 2 スペースでインデントされ、末尾に改行が付きます。

形が予測できることは見た目以上に重要です。結果を消費するスクリプトは、返ってきたものを確認せずにインデックスでアクセスでき、配列の長さは元データの空でない行数と一致します。元データが単一オブジェクトのファイルで、1 要素の配列ではなくそのオブジェクト自体が欲しい場合、その展開は別の作業で、この変換は代わりに行いません。

ほとんどの API は素の配列を受け取りません。{"records": […]}、{"data": […]}、{"items": […]} のように、名前の付いたキーの下にレコードを持つオブジェクトを求め、しばしば件数やバッチ識別子も添えます。この変換は配列を作ってそこで止まります。キー名を作り出すことは、見えない契約を推測することになるからです。

あとから加えるのは簡単で、大きなファイルの末尾で閉じ括弧が抜けやすくエディターで見つけにくい手作業ではなく、意図的に行う価値があります。jq "{records: .}" out.json で包めます。jq "{count: length, records: .}" out.json なら、エンドポイントがおそらく求める件数も一緒に包めます。何かを送る前に API のドキュメントとフィールド名を照らし合わせてください。拒否されたバッチは、たいてい本文が無効だったとしか報告してくれません。

これが NDJSON から出る安全な方向で、隣接する変換先はそうではないため、はっきり書いておく価値があります。同じファイルを CSV、TSV、XLSX、Parquet へ送ると、入れ子のオブジェクトはすべてドット区切りの列に平坦化され、レコードは単一の列集合にすり合わされます。ここではそうした処理は一切行われません。3 段の入れ子を持つ user オブジェクトを含むレコードは、その 3 段の入れ子のまま届きます。

型も同じ理由で保たれます。数値は数値のまま、true は真偽値のまま、null は null のまま、数字に見える文字列は引用符付きのままです。何も推測されません。その必要がないからです。元データはすでに JSON で、行き先も JSON です。各レコードの中のキーの順序も保たれるので、出力は同じデータの別の書き出しと差分を取ることもできます。

どこか 1 行でも解析に失敗すると、何も書き出されません。メッセージは行を特定します。「このファイルは NDJSON として読み込めませんでした——3 行目が有効な JSON ではありません」。部分的な文書は作られず、レコードが黙って読み飛ばされることもありません。

この変換先にとって、この振る舞いは表計算ファイル向けの変換より価値があります。プロセスが書き込み途中で強制終了されたり、ローテーションされたファイルが境界で切れたりしてよくある、途中で切れた最終行は、そうでなければ解析でき検証も通るのに、数の分からないレコードが欠けている文書を作ってしまいます。特定された行を削除するか修復するのはコマンド 1 つで済み、何を取り除いたかも正確にわかります。末尾の空行は問題になりません。ほとんどのライターが残す最後の改行も含めて読み飛ばされます。

出力は 2 スペースのインデントで整形されるので、元データで密な 1 行を占めていたレコードは、末端の値ごとに 1 行と、括弧のための行を占めるようになります。1 レコードあたり十数個のフィールドを持つ平坦なレコードのファイルは、行数がおよそ十数倍に増え、バイト数もすべての行のインデント分だけ増えます。

それはデータではなく、通信の際にはほとんど圧縮で消えます。行き先が人間や差分表示ツールなら、インデントこそが目的です。行き先が容量制限のあるアップロード欄なら、jq -c . を通してコンパクトな形にするか、そもそも受け取り側が本当に 1 つの文書を必要としていたのか考え直してください。そう見えるものの多くは、頼めば NDJSON のまま喜んで受け取ってくれます。

この変換の両方の段階は、値全体に対する操作です。行が配列へ解析されてから初めて何かが書き出され、その配列は 1 回のパスで直列化されます。ピーク時のコストは、元データと解析後の構造と出力文字列の合計です。何もストリーミングされず、そもそもできません。配列は最後の要素が確定するまで完成しないからです。

無料枠の上限は 1 ファイルあたり 100 MB で、実務上の上限はタブそのものです。数十メガバイトなら何も起きませんが、数百メガバイトのレコードになると、ブラウザーが苦しみ始めます。そしてそれはまさに、ストリームを単一の文書に変えることがもはや良い考えではなくなる規模でもあります。NDJSON はどの行の境界でも安全に分割できるので、split -l 200000 で分ければ、それぞれきれいに変換できるファイルになります。

結果を逆方向に変換すると、最初にあったものが正確に返ってきます。トップレベルの JSON 配列は要素ごとに 1 行として書き出されるので、レコードもそのキーも、キーの順序も型も、すべて変わらずに戻ってきます。どちら向きにも累積する非可逆な段階はありません。

これによってこのペアは、移行ではなく作業の中の一手として役立ちます。JSON に変換し、バリデーターやスキーマチェックを実行し、括弧の対応が確認できるちゃんとした JSON エディターで指摘された箇所を直し、また NDJSON に戻し、もともと 1 行ずつを求めていたローダーに修正済みのストリームを渡す、という流れです。NDJSON が転送用の形式のままで、JSON が作業する形になります。

受け取る側が改行区切りの入力を受け付けるなら、そのまま渡してください。BigQuery、ClickHouse、DuckDB、Elasticsearch の一括読み込み、ほとんどのログ収集ツールが入力形式として NDJSON を名指しているのは、まさに単一の配列だと読み手がすべてを一度に保持せざるを得なくなるからです。要件ではなく好みを満たすために変換すると、ファイルは大きくなり読み込みは遅くなります。

いずれにせよ元データは残しておいてください。配列は、単一の値であるということ以外に行にない利点を持たず、行のほうには配列にないいくつもの利点があります。書き換えなしに追記でき、まるごと読み込まずに jq でフィルタリングでき、1 バイトの破損が文書全体ではなく 1 レコードだけを損ないます。

この変換はページの中で動く素の JavaScript です。エンジンはダウンロードされず、ファイルを運ぶリクエストは発生せず、アカウントも 1 日の割り当てもありません。変換中のネットワークタブこそが、この文よりも信頼できる確認方法です。

これが重要なのは、この変換を必要とするファイルが公開情報であることはめったにないからです。イベントの書き出し、監査ログ、スキーマバリデーターへ向かう顧客データの抽出——そのどれもが、まさに組織が Web サービスへの貼り付けを禁じている種類の素材です。何も送信されなければ、禁じるべきことも何もありません。