jq 處理大檔案 JSON:-s 為什麼爆記憶體,串流怎麼寫
結論:幾百 MB 的 JSON 日誌用 jq -s 聚合直接被系統殺掉,換成 reduce inputs 後同樣的統計記憶體只要幾 MB。本文用 220MB、200 萬行樣本實測兩種寫法的耗時與記憶體峰值,講清 -s 和整體解析吃記憶體的機制、JSONL 逐行處理的正道、--stream 路徑事件的寫法,以及 -n --stream 靜默零輸出等三個真實的坑。

jq 本身解析得很快,讓它在幾百 MB 的檔案上翻車的幾乎總是同一個寫法:
-s把整個檔案讀進記憶體拼成一個大陣列,記憶體峰值輕鬆衝到檔案體積的幾倍到十倍。
一、現象:同一份檔案,兩種寫法差 580 倍記憶體
先看一組實測。樣本是 220MB、200 萬行的 JSONL 日誌(每行一個請求記錄,含時間戳、level、path、status、duration_ms、uid 六個欄位),環境是 jq 1.7、Linux x86_64,用 /usr/bin/time -v 取峰值 RSS:
| 寫法 | 任務 | 耗時 | 峰值記憶體 |
|---|---|---|---|
jq -s 'group_by(.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 倍,耗時還更短。這不是 jq 的 bug,-s 的語義本來就是把全部輸入變成一個值——只是大部分人寫聚合時沒意識到這個預設代價。第三方數據也能對上:華為雲社群的 2.3GB JSONL 復盤記錄了完全相同的軌跡,-s 一把梭 OOM,改成串流後 47 秒跑完、RSS 30MB 出頭;dratini.tech 在 2.5GB 樣本上測到 jq -s 直接被 OOM killer 殺掉(>16GB 記憶體的機器),而標準管線 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(...) 提取:
| 寫法 | 耗時 | 峰值記憶體 |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid'(整體解析) |
4.7s | 1.85 GB |
jq --stream 'select(...)'(路徑事件流) |
13.4s | 3.4 MB |
整體解析的記憶體峰值仍然在 1.8GB 量級——jq 必須先把整棵樹建完才開始跑過濾器。--stream 用約 3 倍的耗時換 540 倍的記憶體差距,這就是串流模式存在的意義。記憶體為什麼漲得這麼狠、在哪些環節漲,記憶體佔用從哪來那篇有更完整的模型,這裡只記結論。
三、JSONL 日誌:預設逐行讀才是正道
如果你的「大檔案」其實是一行一個物件的 JSONL 日誌,那 jq 的預設行為就是串流的——每個輸入行獨立解析、獨立輸出,根本不需要 -s:
# 統計每種 level 的條數:逐行讀,配合 shell 聚合
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 解析完一行立刻過濾,被丟棄的行不會做後續建構;把過濾放在變換之後等於白算。-r輸出裸字串。不加-r,輸出是帶引號的 JSON 字串,uniq -c會把"ERROR"和ERROR當成兩種值。
髒行處理用 fromjson?:jq -r 'fromjson? | .level'——解析失敗的行靜默跳過,日誌檔案裡混進截斷行時不至於整條管線斷掉。JSONL 格式本身的規則與場景選擇見 JSONL 檔案實操,那篇講格式,本篇講處理它的具體命令。
四、全域聚合:reduce inputs 串流累加
逐行過濾交給 shell 夠用,但如果要在 jq 內部完成全域聚合(比如按 level 計數、按 path 算平均耗時),關鍵是用 reduce 配 inputs 讓狀態有界:
# 按 level 計數:記憶體只跟結果集大小有關,與檔案體積無關
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl
# 按 path 聚合平均耗時:狀態是 {count, total} 兩個欄位
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,第一條記錄會被當初始值吃掉。- reducer 的狀態必須定形——只維護計數器、累加值這類固定欄位。一旦在 reducer 裡把匹配行 push 進陣列,記憶體又會跟著資料量漲回去,串流就白做了。
這就是上面表格裡 3.5MB 的來源:2GB 的資料流過,留下的只有一個雜湊表。
五、單文件大陣列:--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:先截掉前幾層路徑,再由 fromstream 按子樹重組,華為雲社群那篇有完整示例。
--stream 的代價是慢:路徑事件要把結構展開成一條條標量,同任務耗時約是整體解析的 3 倍。所以決策順序是:JSONL 優先逐行;單文件且目標只是提取少量葉子值,才上 --stream。大檔案怎麼按體積選工具的總覽在大檔案 JSON 打不開怎麼辦。
六、三個真實的坑
坑一:-n --stream 不配 inputs,靜默零輸出。 本機實測踩到的:jq -n --stream 'select(...)' file.json 退出碼 0、無任何輸出、無任何報錯——因為 -n 模式下 jq 不會自動讀輸入,過濾器裡的 select 根本沒有事件可挑。正確寫法是去掉 -n 直接 --stream,或者 -n --stream 配 reduce inputs / 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),但如果你在 shell 裡把輸出重定向到了目標檔案,殘缺檔案已經落盤。工程做法是 staging + rename:先寫到臨時檔案,jq 成功後再 mv 覆蓋目標;需要更細的控制用 --stream-errors 把解析錯誤也當事件處理,在過濾器裡顯式 error 中斷。jsonprettifier 的文章給了完整的原子發布模板。
七、什麼時候別用 jq:Miller 與混合管線
jq 是函數式樹變換語言,擅長深嵌套改寫和結構重組;但當任務退化成「GB 級扁平日誌的過濾和統計」時,有更對口的工具。dratini.tech 在 2.5GB JSONL 上的基準(過濾 + 取列):
| 工具 | 耗時 | 峰值記憶體 |
|---|---|---|
| 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——Miller 一條 mlr --json stats1 頂一段 jq 腳本,且記憶體恆定;rg 能先按行篩掉 90% 無關記錄再交給 jq 時,混合管線最快。極端大檔案的更多路線(ijson、分片、專用檢視器)見大檔案 JSON 打不開怎麼辦。
常見問題
jq -s 處理多大檔案會出問題?
經驗閾值是檔案體積超過可用記憶體的一半就要警惕:解析後的記憶體開销通常是文字的 3-10 倍(本機 220MB 實測 9.5 倍,第三方記錄 4GB 檔案在 16GB 機器上直接 OOM)。先跑 ls -lh 和 free -m 對一下數字,超過就把 -s 換成 reduce inputs。
reduce inputs 前面為什麼要加 -n?
-n 告訴 jq 不要把第一個輸入當作程式的初始輸入,讓 inputs 自己逐條吐出全部記錄。漏寫 -n 時,第一條記錄會被當作 reduce 的初始狀態吃掉,結果裡永遠少第一條——這種丟資料的 bug 不報錯,很難發現。
jq --stream 和普通模式怎麼選?
先看檔案形態:JSONL 日誌預設逐行讀就是串流的,不需要 --stream;單個大文件且只需要提取少量葉子值時,--stream 用約 3 倍耗時換數百倍記憶體差距,值得。需要完整重組子樹時用 truncate_stream + fromstream。檔案能裝進記憶體就別折騰串流,普通寫法更快。
串流處理遇到損壞的 JSON 行怎麼辦?
JSONL 裡用 fromjson? 跳過解析失敗的行,不讓一條髒行斷掉整條管線。單文件大 JSON 裡中途 parse error 會讓管線失敗,用 staging 檔案加 rename 做原子發布,避免把已經吐出的部分結果留在目標檔案裡;需要顯式控制用 --stream-errors。