JSON Toolkit

jq で大容量 JSON を捌く:-s がメモリを食い潰す理由とストリーミングの書き方

要点:数百 MB の JSON ログを jq -s で集計すると OOM で殺されますが、reduce inputs に書き換えると同じ統計が数 MB のメモリで済みます。220MB・200 万行のサンプルで両者の実行時間とメモリ峰值を実測し、-s と全体解析がメモリを消費する仕組み、JSONL の行単位処理、--stream のパスイベント、そして -n --stream が無出力で終わる罠など三つの落とし穴を解説します。

実践約 6 分で読めます2026-11-12 公開2026-11-12 更新
jq のストリーミング処理と -s のメモリ消費を対比した図

jq 自体の解析は速いのに、数百 MB のファイルで死ぬのはほぼ同じ書き方が原因です。-s は入力全体を一つの巨大な配列としてメモリに読み込み、ピーク RSS はファイルサイズの数倍から十倍に達します。

現象:同じファイルで書き方次第でメモリが 580 倍変わる

まず実測値を見てください。サンプルは 220MB・200 万行の JSONL ログ(1 行 1 リクエスト記録、timestamp・level・path・status・duration_ms・uid の 6 フィールド)。環境は jq 1.7、Linux x86_64、ピーク RSS は /usr/bin/time -v で取得しています。

書き方 タスク 実行時間 ピーク RSS
jq -s 'group_by(.level) | ...' level 別に全量集計 10.1s 2.08 GB(ファイルの約 9.5 倍)
jq -n 'reduce inputs ...' 同じ集計 4.7s 3.5 MB
jq -r 'select(...) | .path' 行単位のフィルタ 2.6s 3.6 MB

同じ統計処理なのに、書き方を変えるだけでメモリが 580 分の 1 になり、実行時間まで短くなります。これは jq のバグではありません。-s の意味論はもともと「入力全部を一つの値にする」であり、ほとんどの人は集計を書くときにこのデフォルトのコストを計算に入れていないだけです。第三者のデータも一致しています。華為云コミュニティの 2.3GB JSONL 検証では -s で OOM、ストリーミングに書き換えると 47 秒・RSS 30MB 強で完了。dratini.tech の 2.5GB 計測では jq -s が 16GB 超のマシンでも OOM killer に殺され、通常パイプラインは 48.2 秒・84MB で完走しています。

結論を先に:ファイルサイズが利用可能メモリの半分を超えたら -s は候補から外す。手を動かす前に三つ測りましょう。ls -lh でサイズ、free -m で空きメモリ、wc -l で行数です。

-s と全体解析がメモリを食べる仕組み

jq -s(slurp)の公式定義は「入力全部を読み込み、一つの配列に入れる」です。実際のコストはテキストそのものよりはるかに大きくなります。jq は解析後、C 構造体のツリーを保持し、オブジェクト・配列・文字列・数値のそれぞれがノードとメタデータを持ちます。220MB のテキストは構造化されると 2GB 強になり、約 9.5 倍に膨張します。group_by はさらにメモリ上でソートとグルーピングを行い、ピークを押し上げます。

単一の巨大 JSON も同じです。同じログを jq -s '.' で 300MB のトップレベル配列に束ね、通常のフィルタ .[] | select(...) で抽出した結果がこちらです。

書き方 実行時間 ピーク RSS
jq '.[] | select(.level=="ERROR") | .uid'(全体解析) 4.7s 1.85 GB
jq --stream 'select(...)'(パスイベントストリーム) 13.4s 3.4 MB

全体解析でもピークは 1.8GB 前後です。jq はツリー全体を構築し終えるまでフィルタを始められないからです。--stream は約 3 倍の時間を払って 540 分の 1 のメモリに抑えます。メモリがどの工程で膨らむかの詳細なモデルはメモリ消費の内訳で扱っています。

JSONL ログ:デフォルトの行単位読みこそ正攻法

扱っている「巨大ファイル」が実は 1 行 1 オブジェクトの JSONL ログなら、jq のデフォルト動作は既にストリーミングです。各行は独立して解析・出力され、-s は不要どころか有害です。

# level ごとの件数を集計:行単位で読み、シェル側で集計
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# フィルタ + 抽出:select を先頭に置き、不一致行は即座に捨てる
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

習慣にしたい細部が二つあります。

  • select はパイプラインの最前面へ。jq は 1 行解析するや否やフィルタするので、変換の後ろに置くと無駄な計算になります。
  • -r で素の文字列を出力。-r がないと出力は引用符付きの JSON 文字列になり、uniq -c は "ERROR" と ERROR を別物として数えます。

壊れた行は fromjson? で処理します。jq -r 'fromjson? | .level' とすれば解析失敗行を黙ってスキップし、途中の切れた行でパイプライン全体が止まりません。JSONL というフォーマット自体の性質は JSONL ファイル実践に譲り、ここでは処理コマンドに集中します。

全量集計:reduce inputs で状態を有界に保つ

行単位のフィルタはシェルに任せれば十分ですが、level 別カウントや path 別平均のように jq 内部で集計を完結させたいときは、reduce と inputs の組み合わせで状態を固定サイズに保ちます。

# level 別カウント:メモリは結果セットのサイズにのみ依存
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# path 別平均処理時間:状態は {count, total} の 2 フィールド
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

ポイントは二つです。

  • -n は「最初の入力を初期値にしない」の意味で、inputs が全レコードを順に吐きます。-n を忘れると先頭 1 件が初期値として飲み込まれます。
  • reducer の状態は固定形に保ちます。カウンタと累積値だけ。一致行を配列に push し始めた瞬間、メモリは再びデータ量に比例し、ストリーミングの意味が消えます。

冒頭の表の 3.5MB はここから来ています。2GB のデータが流れても残るのはハッシュテーブル一つです。

実運用では、状態の設計を最初に決めるのが安全です。「最終的に知りたいのは何で、その計算にレコード全文は必要か」。p95 のような分位数は全値を保持せざるを得ないので配列が必要になり、その場合は t-digest などメモリ上界を持つ近似アルゴリズムに寄せるか、時刻で区切ったチャンク分割を検討します。逆に合計・件数・最大最小は定数メモリで完結するので、jq の reduce の範囲で済みます。処理を分割する判定材料として、この線引きを先に引いておくとパイプラインが破綻しにくくなります。

単一の巨大配列:--stream のパスイベント

入力が「一つの巨大なトップレベルドキュメント」(数百 MB のエクスポートなど)で行境界がない場合は --stream を使います。完全な値の代わりに「パス + リーフ値」のイベント列を出力します。

# イベントはパス配列 + スカラー値の形
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

イベントストリームから抽出する際はパス全体の形状を照合します。深度・メンバ名・配列インデックスの位置まで見ないと、最後の要素だけ見る書き方はネスト内部の同名キーまで拾ってしまいます。

# rows[i].id のみ取得。meta.id や深い場所の同名キーは無視
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

集計はやはり固定形の reduce inputs です(-n --stream の場合は inputs での明示的な消費が必須、次節の落とし穴参照)。一致イベントを完全なオブジェクトに再構築したい場合は truncate_stream と fromstream を組み合わせます。ファイルサイズ別のツール選定の全体像は大容量 JSON が開けないときにあります。

実際に踏んだ三つの落とし穴

落とし穴一:-n --stream に inputs がないと無出力で終わる。 実測で踏みました。jq -n --stream 'select(...)' file.json は終了コード 0、出力もエラーもゼロ。-n モードでは jq が入力を自動で読まないため、フィルタの select に渡るイベントが一つもないのです。正しくは -n を外して --stream、または -n --stream に reduce inputs を組むことです。「成功したのに空」という失敗は最もデバッグしづらく、パイプラインを組む前に小サンプルで出力を確認すべきです。

落とし穴二:--stream はスカラーリーフしか出さない。 空オブジェクトと空配列には値イベントがありません。{"a":{}} はパス閉鎖イベント(length == 1)しか出さず、length == 2 だけを見るフィルタは空コンテナを黙って飲み込みます。統計に空コンテナを含めるかは明示的に決めましょう。

落とし穴三:途中の parse error で部分結果が出る。 ストリーミングパイプラインは前半を出力し終えた後、ファイル末尾の壊れた JSON で失敗することがあります。jq 1.7 は既定で検出時に異常終了します(実測:[1,] で parse error: Expected another array element at line 1, column 4、終了コード 5)。ただしシェルで出力をファイルへリダイレクトしていると、中途半端なファイルが既に書き込まれています。対策は staging + rename です。一時ファイルに書き、jq 成功後に mv で置き換える。より細い制御は --stream-errors で解析エラーをイベント化し、フィルタ内で明示的に error を起こします。

jq を使わない方がいいとき:Miller とハイブリッド

jq は関数型のツリー変換言語で、深いネストの再構築が得意です。しかしタスクが「GB 級フラットログのフィルタと集計」に単純化されるなら、より適した道具があります。dratini.tech の 2.5GB JSONL 計測(フィルタ + 列抽出)です。

ツール 実行時間 ピーク RSS
jq 通常パイプライン 48.2s 84 MB
jq -s OOM(16GB 超でも殺される) —
Miller(mlr --json) 11.4s 18 MB
ripgrep + jq ハイブリッド 8.1s 32 MB

選定の目安:深いネスト・構造変換・CI での普遍性なら jq。数 GB のフラット JSONL 統計、p95、JSONL→TSV なら mlr --json stats1 一発で、メモリも一定です。rg で 9 割の無関係な行を先に落とせるならハイブリッドが最速です。

よくある質問

jq -s はどのくらいのファイルから危険ですか?

経験則では、ファイルサイズが利用可能メモリの半分を超えたら警戒です。解析後のメモリはテキストの 3〜10 倍(220MB 実測で 9.5 倍、第三者記録では 4GB ファイルが 16GB マシンを OOM)。まず ls -lh と free -m を比べ、近いなら -s を reduce inputs に置き換えます。

reduce inputs の前になぜ -n が要るのですか?

-n は「最初の入力をプログラムの初期値にしない」という指示で、inputs が全レコードを自前で吐けるようにします。-n を忘れると先頭レコードが reduce の初期状態として消え、結果から永远に 1 件欠けます。エラーを出さないデータ損失なので非常に厄介です。

jq --stream と通常モードの選び方は?

まずファイル形態を見ます。JSONL なら行単位で既にストリーミング、--stream は不要。単一の巨大ドキュメントから少数のリーフ値だけ欲しいなら、約 3 倍の時間と引き換えに数百倍メモリを節約する --stream が割に合います。メモリに収まるなら通常書き方が速いです。

ストリーミング中に壊れた JSON 行が出たら?

JSONL なら fromjson? で解析失敗行をスキップします。単一ドキュメントの途中 parse error は実行全体を失敗させるので、staging ファイルと rename で原子発布にし、部分結果が目標ファイルに残らないようにします。細かい制御は --stream-errors を使います。