JSON Toolkit

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.

Pokročilý~6 min čteníPublikováno 2026-11-12Aktualizováno 2026-11-12
Porovnání paměti mezi proudovým jq a -s u velkých JSON souborů

jq parsuje rychle, ale téměř každá smrt u souboru pár set MB vede ke stejnému flagu: -s nahraje 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.
  • -r pro syrové řetězce. Bez něj je výstupem JSON řetězec v uvozovkách a uniq -c spočítá "ERROR" a ERROR jako 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:

  • -n znamená, že jq nesmí zkonzumovat první vstup jako počáteční hodnotu; inputs sám vysílá každý záznam. Zapomenete -n a 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.