Node.js で大きな JSON を読む:stream-json ストリーミング解析とバックプレッシャー実践
要点:186MB の JSON 配列を readFileSync + JSON.parse で読むとピークメモリは 612MB。stream-json の streamArray で逐次消費に変えると 104MB で一定に保たれます。本稿では 4 種類の読み方の実測比較を示し、for await がなぜ自然にバックプレッシャーを生むか、data イベントでどう失われるか、書き込み側の highWaterMark と drain の設定方法を解説します。

186MB の JSON をインポートしただけでメモリが 600MB に達するのは、ファイルが大きいからではなく、JSON.parse がテキスト全体を一気にオブジェクトグラフ全体へ交換したからです。読み方を変えればメモリ曲線は平坦になります。
一、症状:186MB のファイルでピーク 612MB
サーバー側のインポート処理でこの問題が最も起きやすい:注文の定期同期、ログのクリーニング、履歴データの一括投入。典型的な実装は次のとおりです。
const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);
この書き方を Node 22.13 で実測しました。サンプルは 480,000 件の注文オブジェクト配列、ファイル 186MB(文字列・ネストしたオブジェクト・配列を含む現実的な構造)。/usr/bin/time -v で測った結果、読み込みは 1.3 秒ですが、Maximum resident set size は 612MB——ファイルの 3.3 倍です。V8 の老世代既定上限は 1.4〜2GB なので、この種のタスクが数本並行するだけでコンテナは OOM Kill を待つばかりになります。
内訳は単純です:テキストがメモリに 1 部(約 186MB)、parse 後のオブジェクトグラフがさらに 1 部(文字列キー・ネストヘッダ・配列にそれぞれ追加コスト)、加えて解析中の一時確保が積み上がり、600MB に達するのは当然です。
二、原因:JSON.parse は全体テキストを全体グラフと交換する
JSON.parse の契約は「完全なテキストを渡せば、完全なオブジェクトグラフを返す」です。解析開始前に全テキストが揃っていることを要求し、解析終了後に結果を一括で返すだけ。途中で「まず先頭 1,000 件を」のような機会は一切ありません。
オブジェクトグラフのコストは JSON のメモリ計算 で体系的に測定済みです:文字列は実際の空間を消費し、オブジェクトはキーごとにスロットを取り、配列は要素種類で幅が決まる。十数 MB の JSON が解析後に 3〜5 倍になるのは常態で、ピークはさらに上乗せされます。
しかし大半のインポート処理に全体グラフは不要です:逐次書き込み・逐次フィルタ・逐次変換で、処理済みレコードは即 GC に回せます。必要なのは「1 件解析したら 1 件渡す」能力——それがまさにストリーミング解析の定義です。
三、改善:streamArray で逐次消費、for await が自然にバックプレッシャーを生む
stream-json はパーサーを Transform ストリームとして実装し、トークン単位で解析するためファイル全体を待ちません。トップレベルが配列なら、streamArray() は各要素の解析完了の瞬間に {key, value} を発行します:
const fs = require('fs');
const { chain } = require('stream-chain');
const { parser } = require('stream-json');
const { streamArray } = require('stream-json/streamers/StreamArray');
async function importOrders(filePath) {
const pipeline = chain([
fs.createReadStream(filePath, { highWaterMark: 64 * 1024 }),
parser(),
streamArray(),
]);
for await (const { key, value } of pipeline) {
await saveToDb(value);
}
}
同じ 186MB・48 万件で、この書き方のピーク RSS は 104MB、全編一定です。メモリ上に存在するのは「現在の要素 + パーサー状態」だけで、処理済み要素はすぐ回収されます。
見落としやすい点:for await は saveToDb の完了を待つ間、パーサーから次のレコードを引きません。DB が遅ければ読み込みも遅くなる——これがバックプレッシャーで、追加コード不要で自然に生まれます。dev.to の 4GB 市政交通ログ取り込み事例も同じチェーンで、pick({filter:'data'}) を加えてもメモリ曲線は同様に平坦でした。
四、書き込み側の失守:一時停止しない data イベントがメモリを押し戻す
ストリーミング解析が抑えるのは読み込み側だけです。書き込み側がバックプレッシャーを受け止めないと、メモリは再び増加します。典型的な失敗は data イベント内で非同期書き込みしつつ書き込みバッファを無視するパターン:
// 誤り:data イベント + 非同期書き込み、バックプレッシャー完全失效
readable.on('data', async (chunk) => {
await slowWrite(chunk); // ストリームは待たない、バッファは膨張し続ける
});
data モードではストリームが流れ続けるため、slowWrite がどれほど遅くても上流は止まりません。同じ 186MB サンプルで、100 チャンクごとに 1ms 遅延する遅い Writable につないで比較した結果、バックプレッシャー無視でピーク RSS 407MB、write() が false を返したら await once(sink, 'drain') で一時停止する書き方では 161MB——差分 246MB はまさに書き込みバッファに溜まったデータです。
// 正しい:write() が false を返したら一時停止、drain 後に再開
for await (const { value } of pipeline) {
if (!sink.write(value)) {
await once(sink, 'drain');
}
}
補足を二つ:手動でストリームを繋ぐ場合は各ストリームに highWaterMark を明示設定する(objectMode の既定 16 は大きなオブジェクトには大きすぎ)、pipe() の代わりに pipeline()(stream/promises)を優先する——エラー伝播と後始末は任せられます。
五、実測比較:4 種類の書き方のピークメモリ
| 書き方 | サンプル | ピーク RSS | 所要時間 | 適用場面 |
|---|---|---|---|---|
| readFileSync + JSON.parse | 186MB / 48 万件 | 612MB | 1.3s | 小さいファイル・ランダムアクセス |
| streamArray + for await + 遅い DB 書き込み(各 0.5ms) | 同上 | 104MB(一定) | DB の速度に従う | 逐次投入・逐次変換 |
| streamArray + data イベント書き込み、背圧なし | 同上 | 407MB | 約 10s | 反面教師 |
| streamArray + write()/drain 背圧 | 同上 | 161MB | 約 10s | 結果の落盤・転送 |
環境:Node 22.13、/usr/bin/time -v で Maximum resident set size を測定。サンプルは合成データで、単回実行の値です。数値はこのサンプルでの桁の結論であり、普遍定数ではありません。
注目すべき読み取りは二つ:第 1 と第 2 の差は 6 倍のメモリで、代償は「1.3 秒」が「DB に従う」に変わること。第 3 と第 4 の差は 2.5 倍で、読み側だけストリーミングして書き側の背圧を疎かにすると半分しか解決しないことを示します。
六、診断:バックプレッシャーが本当に機能しているか確認する
本番のメモリ問題は当てずっぽうでは直せません。Tencent Cloud の背圧排查記事は実用的な手順を示しています:
- 重要なストリームに一時的に
'pause'と'resume'のログを掛ける。大流量リンクで一度も pause が出ないなら、どこかがデータをメモリに溜めていると断定できる; writable.writableLength(書き込みバッファのバイト数)を見る。増え続けるなら消化されていない;process.memoryUsage()で RSS を定期サンプリングして曲線を描き、「上昇型」(溜めている)と「鋸歯状の安定」(正常回収)を区別する。
for await では pause と resume のログが必ず交互に出ます。まったく出ないなら、data リスナーの混入か await 忘れを疑ってください。
七、ストリーミングが不要なとき
ストリーミングは既定の答えではありません。数十 MB 以内でキーによるランダムアクセスが必要なら、JSON.parse 一発の方がむしろ簡単です。ブラウザで大きなファイルを開くのは別問題域で、大きな JSON ファイルの開き方 ではビューアー選定を扱います。ストリーミング解析の適用境界は明確です:
- トップレベルが配列(または JSONL で行分割可能)で、消費が逐次処理、先を読み返す必要がない;
- ファイルサイズが制御不能またはヒープ余裕を大きく超え、一度のインポートでメモリを倍増させられない;
- 消費側に速度差(DB 書き込み・下流 API 呼び出し)があり、全速灌流ではなく背圧が必要。
トップレベルの構造が不規則なら、まず JSON 解析・整形 ツールで構造を確認してから読み方を選ぶ。コマンドライン側の処理は jq で大きな JSON を扱う で、jq --stream と streamArray は同じ発想の別ランタイム実装です。
よくある質問
stream-json は JSON.parse よりどれくらい遅い?
純粋な解析速度では JSON.parse が速い:186MB サンプルで 1.3 秒対し、書き込み遅延なしの streamArray は約 7 秒(トークン解析 + レコード単位の構築コスト)。ストリーミングの利得はすべてメモリ側にあり、ピークは 612MB から 104MB へ。インポート処理のボトルネックは DB 書き込みなので、数秒の解析コストで 6 倍のメモリ余裕を買うのは通常妥当な取引です。ミリ秒級 API 応答内では不向きです。
for await の背圧と手動 pause/resume は同じものか?
意味的には等価です:for await はループ本体が未完了の間、読み取り可能ストリームを自動一時停止する。これは write() が false を返したら pause()、drain で resume() を呼ぶのと同じです。違いは言語機構に委ねられて漏れない点で、手動は一箇所でも漏れるとチェーン全体の背圧が切れます。
トップレベルが配列ではなく一つの巨大オブジェクトの場合は?
stream-json には streamObject()(キーごとに発行)と Pick フィルター(指定サブツリーのみ解析)があります。数個のフィールドだけ要るなら Pick + JSONPath で全体グラフを必要部分に縮小できます。複数文書混合(JSON Lines、JSON Seq)は先に行分割し、行単位の独立 JSON として処理するのが勧めです。
結果を JSONL として書き出したり下流へ転送したりするには?
書き込み側も同じ背圧問題です:fs.createWriteStream や http.request では write() の戻り値を確認し、false なら await once(stream, 'drain')。あるいは書き込みストリームを pipeline() に接続して Node に管理させます。検証は実行後の RSS 曲線が安定していることと、writableLength が持続増加していないことの確認で十分です。
インポート処理に素早くメモリ監視を足すには?
最小構成は 100ms ごとに process.memoryUsage().rss を配列へ採取し、終了時に最大値を表示。より正確には /usr/bin/time -v node task.js で Maximum resident set size を直接確認。コンテナ内ではアラート線をメモリ上限の 70% に置き、GC の余裕を残します。