jq a velké JSON soubory: proč -s vyhodí paměť a jak zpracovávat proudově
Shrnutí: Agregace stovek MB JSON logů přes jq -s končí OOM, zatímco reduce inputs vytvoří tutéž statistiku s několika MB RAM. Změřeno na vzorku 220 MB a 2 milionů řádků: slurp kulminuje na 2,08 GB oproti 3,5 MB pro proudový reduktor. Článek vysvětluje mechanismus spotřeby paměti, zpracování JSONL řádek po řádku, události cest --stream a tři reálné pasti, včetně tichého prázdného výstupu -n --stream.

jq parsuje rychle, ale téměř každá smrt u souboru pár set MB vede ke stejnému flagu:
-snahraje celý vstup do jednoho obřího pole a špičkový RSS snadno dosáhne násobku velikosti souboru.
Jeden soubor, dva dotazy: 580krát méně paměti
Začněme měřením. Vzorek je JSONL log o velikosti 220 MB a 2 000 000 řádcích (jeden záznam požadavku na řádek: timestamp, level, path, status, duration_ms, uid). Prostředí: jq 1.7 na Linux x86_64, špičkový RSS snímaný přes /usr/bin/time -v:
| Dotaz | Úloha | Doba | Špičkový RSS |
|---|---|---|---|
jq -s 'group_by(.level) | ...' |
počítání podle level | 10,1s | 2,08 GB (~9,5x velikost souboru) |
jq -n 'reduce inputs ...' |
totéž počítání | 4,7s | 3,5 MB |
jq -r 'select(...) | .path' |
filtr řádek po řádku | 2,6s | 3,6 MB |
Tutáž statistika, 580krát méně paměti, a ještě rychleji. Není to bug jq — -s znamená po definici „načti všechno do pole"; většina lidí si prostě ten implicitní náklad nevyčíslí. Zahraniční zdroje souhlasí: zpráva o 2,3 GB JSONL z komunity Huawei Cloud vypráví přesně tentýž příběh — OOM se slurp, poté proudový reduktor, který skončí za 47 sekund při něco málo přes 30 MB RSS. Dratini.tech naměřila na 2,5 GB vstupu jq -s zabitý OOM killerem i na stroji s 16 GB+, zatímco obyčejná pipeline doběhla za 48,2s při 84 MB.
Závěr hned na začátek: přesáhne-li soubor polovinu dostupné paměti, -s není ani kandidát. Změřte tři věci, než cokoli napíšete: ls -lh kvůli velikosti, free -m kvůli paměťové rezervě, wc -l kvůli počtu řádků.
Kam paměť opravdu odchází
jq -s (slurp) je dokumentováno jako „načíst všechny vstupy do pole". Skutečné náklady daleko přesahují text: po parsování jq drží strom C struktur a každý objekt, pole, řetězec i číslo nese vlastní uzel s metadaty. Našich 220 MB textu se stalo něco přes 2 GB struktur — nafouknutí zhruba 9,5x. group_by navíc řadí a grupuje v paměti a pík dále zesiluje.
Jeden velký JSON dokument se chová stejně. Zabalení téhož logu do kořenového pole o 300 MB a vytažení obyčejným filtrem:
| Dotaz | Doba | Špičkový RSS |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid' (celý dokument) |
4,7s | 1,85 GB |
jq --stream 'select(...)' (události cest) |
13,4s | 3,4 MB |
Plné parsování kulminuje dál kolem 1,8 GB — jq postaví celý strom, než se filtr spustí. --stream vymění zhruba 3x běhový čas za 540krát menší paměť. Detailní model toho nafouknutí rozvedli v Odkud se bere paměť.
JSONL logy: čtení řádek po řádku už je stream
Je-li váš „velký soubor" ve skutečnosti JSONL — jeden objekt na řádek —, je výchozí chování jq už proud: každý řádek se parsuje a vysílá nezávisle, a -s není jen zbytečné, je škodlivé:
# počítání podle level: řádek po řádku, agregace v shellu
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head
# filtr + extrakce: select nejdřív, neodpovídající řádky hned zahozeny
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5
Dva návyky, které si vynuťte:
selectúplně na začátku pipeline. jq filtruje, jakmile je řádek sparsován; filtrovat po transformacích znamená plýtvat výpočtem.-rpro syrové řetězce. Bez něj je výstupem JSON řetězec v uvozovkách auniq -cspočítá"ERROR"aERRORjako dvě různé hodnoty.
Pro poškozené řádky použijte fromjson?: jq -r 'fromjson? | .level' tiše přeskočí řádky, které nejdou sparsovat, a uříznutý fragment nezabije celou pipeline. Samotný formát popisuje Praktická příručka JSONL; tento článek pojednává o příkazech, které jej zpracovávají.
Globální agregace: reduce inputs drží stav omezený
Filtrování řádek po řádku patří shellu, ale když musí agregace proběhnout uvnitř jq — počítadla podle level, průměrná doba podle path —, je klíčem reduce s inputs, pro omezený stav:
# počítání podle level: paměť následuje velikost výsledku, ne souboru
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl
# průměrná doba podle path: stav je pevná dvojice {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
| map_values(.total / .count)' app.jsonl
Dva detaily:
-nznamená, že jq nesmí zkonzumovat první vstup jako počáteční hodnotu;inputssám vysílá každý záznam. Zapomenete-na první záznam je spolknut jako počáteční stav.- Stav reduktoru musí mít pevnou podobu — jen počítadla a akumulátory. Jakmile nasunete odpovídající řádky do pole uvnitř reduktoru, paměť zase roste s objemem dat a proud už nestojí za nic.
Proto těch 3,5 MB v tabulce: prošly dva gigabajty, zbyla jen hašovací tabulka.
Jeden velký dokument: události cest --stream
Když vstupem je jediný obří kořenový dokument (export pár set MB bez hranic řádků), použijte --stream. Místo plných hodnot vysílá sekvenci událostí „cesta + listová hodnota":
# událost vypadá takto: pole cesty + skalár
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"
Vytahování z toku událostí vyžaduje spárování úplného tvaru cesty — hloubku, názvy členů, pozice indexů —, protože kontrola jen poslední složky chytne i stejnojmenné klíče ve vnořených objektech:
# jen rows[i].id, ignorujíce meta.id a hlubší jmenovce
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json
Agregace zůstává reduce inputs pevné podoby (u -n --stream je nutné události konzumovat přes inputs — viz pasti). K rekonstrukci — přeměně toku událostí zpět na celé objekty — spojujte truncate_stream a fromstream. Přehled volby nástrojů podle velikosti je v JSON soubor moc velký?.
Tři reálné pasti
Past první: -n --stream bez inputs nevypisuje vůbec nic, potichu. Zjištěno na tomto stroji: jq -n --stream 'select(...)' file.json končí kódem 0, bez výstupu i chyby — v režimu -n jq nečte vstup a select filtru nedostane ani jednu událost. Správně: odstraňte -n a použijte holé --stream, nebo spojte -n --stream s reduce inputs. Tato třída selhání „úspěch, ale prázdno" se ladí nejhůř; validujte na malém vzorku, dřív než zapletete pipeline.
Past druhá: --stream vysílá jen skalární listy; prázdné objekty a pole nemají událost hodnoty. {"a":{}} vytvoří jen událost uzavření cesty (typu length == 1) a filtr po length == 2 tiše spolkne prázdné kontejnery — rozhodněte explicitně, zda se počítají do vašich statistik.
Past třetí: částečný výsledek po chybě parsování v půlce souboru. Proudová pipeline může už vypustit polovinu svého výstupu, než narazí ke konci na rozbitý JSON. jq 1.7 padá hlasitě — [1,] vyprodukovalo parse error: Expected another array element at line 1, column 4 s kódem 5 v našem testu — ale pokud váš shell přesměrovává stdout do cílového souboru, useknutý výsledek už leží na disku. Inženýrský štít: staging plus rename — zapisovat do dočasného souboru a přemístit na cíl až po úspěšném běhu jq. Pro jemnější kontrolu mění --stream-errors chyby parsování na události, které můžete zpracovat a explicitně přerušit přes error.
Kdy jq nepoužít: Miller a hybridní pipeline
jq je funkcionální jazyk transformace stromů, silný v hluboké restrukturalizaci. Jakmile ale úloha degeneruje v „profiltruj a spočítej gigabajty plochých logů", existují lépe střižené nástroje. Benchmark dratini.tech na 2,5 GB JSONL (filtr + výběr sloupců):
| Nástroj | Doba | Špičkový RSS |
|---|---|---|
| obyčejná jq pipeline | 48,2s | 84 MB |
| jq -s | OOM (zabit i s 16 GB+) | — |
| Miller (mlr --json) | 11,4s | 18 MB |
| ripgrep + jq hybrid | 8,1s | 32 MB |
Pravidlo: hluboké zanoření, restrukturalizace, všudypřítomnost v CI — jq. Ploché statistiky na gigabajtech, percentily p95, JSONL do TSV — jediné mlr --json stats1 nahradí jq skript při konstantní paměti. A pokud ripgrep dokáže odmítnout 90 % zbytečných řádků před jq, hybrid je nejrychlejší.
FAQ
Od jaké velikosti je jq -s nebezpečné?
Praktická hranice: jakmile soubor přesáhne polovinu dostupné paměti, nedůvěřujte. Paměť po parsování bývá typicky 3 až 10x text (9,5x u našich 220 MB; zahraniční zprávy popisují soubor 4 GB zabíjející stroj 16 GB). Nejdřív porovnejte ls -lh s free -m a blízko hranice vyměňte -s za reduce inputs.
Proč -n před reduce inputs?
-n říká jq, ať nezkonzumuje první vstup jako počáteční hodnotu programu, aby inputs samo vysílalo každý záznam. Bez -n se první záznam stane počátečním stavem reduce a tiše zmizí z výsledku — ztráta dat bez jediné chyby.
Jak vybrat mezi --stream a běžným režimem?
Nejdřív se podívejte na tvar souboru. JSONL je už proud řádek po řádku; --stream nic nepřináší. U jediného velkého dokumentu, z něhož chcete jen pár listových hodnot, vymění --stream zhruba 3x čas za stokrát menší paměť. Vejde-li se soubor do paměti, je běžné jq prostě rychlejší.
Co s poškozenými řádky při streamování?
V JSONL fromjson? přeskočí řádky, které nejdou sparsovat, aby jediný špinavý řádek nezabil pipeline. U jediného velkého dokumentu svrhne chyba parsování v půlce souboru celý běh — publikujte atomicky přes staging soubor a rename, nebo použijte --stream-errors pro explicitní kontrolu.