jq a duże pliki JSON: dlaczego -s wysadza pamięć i jak przetwarzać strumieniowo
Podsumowanie: Agregacja setek MB logów JSON przez jq -s kończy się OOM, podczas gdy reduce inputs wytwarza tę samą statystykę z kilkoma MB RAM. Zmierzono na próbce 220 MB i 2 milionów linii: slurp kulminuje na 2,08 GB wobec 3,5 MB dla reduktora strumieniowego. Artykuł wyjaśnia mechanizm zużycia pamięci, przetwarzanie linia po linii JSONL, zdarzenia ścieżek --stream oraz trzy realne pułapki, w tym ciche puste wyjście -n --stream.

jq parsuje szybko, ale niemal każda śmierć przy pliku kilkuset MB sprowadza się do tego samego flaga:
-sładuje całe wejście do jednego gigantycznego tablicy, a szczytowy RSS łatwo osiąga wielokrotność rozmiaru pliku.
Jeden plik, dwa zapytania: 580 razy mniej pamięci
Zacznijmy od pomiaru. Próbka to log JSONL o rozmiarze 220 MB i 2 000 000 linii (jeden rekord żądania na linię: timestamp, level, path, status, duration_ms, uid). Środowisko: jq 1.7 na Linux x86_64, szczytowy RSS rejestrowany przez /usr/bin/time -v:
| Zapytanie | Zadanie | Czas | Szczytowy RSS |
|---|---|---|---|
jq -s 'group_by(.level) | ...' |
liczenie po level | 10,1s | 2,08 GB (~9,5x rozmiaru pliku) |
jq -n 'reduce inputs ...' |
to samo liczenie | 4,7s | 3,5 MB |
jq -r 'select(...) | .path' |
filtr linia po linii | 2,6s | 3,6 MB |
Ta sama statystyka, 580 razy mniej pamięci, i szybciej. To nie błąd jq — -s z definicji znaczy «wczytaj wszystko do tablicy»; większość ludzi po prostu nie wycenia tego domyślnego kosztu. Źródła zewnętrzne się zgadzają: relacja o 2,3 GB JSONL ze społeczności Huawei Cloud opowiada dokładnie tę samą historię — OOM przy slurp, potem reduktor strumieniowy kończący w 47 sekund przy nieco ponad 30 MB RSS. Dratini.tech zmierzyło na 2,5 GB wejścia jq -s ubite przez OOM killera nawet na maszynie z 16 GB+, podczas gdy zwykły pipeline kończył w 48,2s przy 84 MB.
Wniosek na początek: jeśli plik przekracza połowę dostępnej pamięci, -s nie jest nawet kandydatem. Zmierz trzy rzeczy, zanim cokolwiek napiszesz: ls -lh dla rozmiaru, free -m dla zapasu pamięci, wc -l dla liczby linii.
Dokąd naprawdę ucieka pamięć
jq -s (slurp) jest udokumentowane jako «wczytaj wszystkie wejścia do tablicy». Realny koszt daleko przekracza tekst: po parsowaniu jq utrzymuje drzewo struktur C, a każdy obiekt, tablica, string i liczba niesie własny węzeł z metadanymi. Nasze 220 MB tekstu stały się nieco ponad 2 GB struktur — rozdęcie około 9,5x. group_by dodatkowo sortuje i grupuje w pamięci, wzmacniając szczyt.
Pojedynczy duży dokument JSON zachowuje się tak samo. Pakując ten sam log w tablicę korzeniową 300 MB i wyciągając zwykłym filtrem:
| Zapytanie | Czas | Szczytowy RSS |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid' (cały dokument) |
4,7s | 1,85 GB |
jq --stream 'select(...)' (zdarzenia ścieżek) |
13,4s | 3,4 MB |
Pełne parsowanie kulminuje nadal w okolicach 1,8 GB — jq buduje całe drzewo, zanim filtr się wykona. --stream wymienia mniej więcej 3x czas wykonania na pamięć 540 razy mniejszą. Szczegółowy model tego rozdęcia rozwinęliśmy w Skąd bierze się pamięć.
Logi JSONL: odczyt linia po linii to już strumień
Jeśli twój «duży plik» to w rzeczywistości JSONL — jeden obiekt na linię —, domyślne zachowanie jq to już strumień: każda linia jest parsowana i emitowana niezależnie, a -s nie jest tylko zbędne, jest szkodliwe:
# liczenie po level: linia po linii, agregacja w shellu
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head
# filtr + ekstrakcja: select najpierw, niedopasowane linie od razu wyrzucone
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5
Dwa nawyki do wyrobienia:
selectna samym początku pipeline. jq filtruje, jak tylko linia jest sparsowana; filtrowanie po transformacjach marnuje obliczenia.-rdla surowych stringów. Bez niego wyjściem jest cudzysłowowany string JSON, auniq -cpoliczy"ERROR"iERRORjako dwie różne wartości.
Dla uszkodzonych linii użyj fromjson?: jq -r 'fromjson? | .level' po cichu pomija linie nieprzeparsowalne, a ucięty fragment nie zabija całego pipeline. Sam format opisuje Praktyczny podręcznik JSONL; ten artykuł dotyczy poleceń, które go przetwarzają.
Agregacja globalna: reduce inputs trzyma stan ograniczony
Filtrowanie linia po linii należy do shella, ale gdy agregacja musi dziać się w samym jq — liczniki po level, średni czas po path —, kluczem jest reduce z inputs, dla ograniczonego stanu:
# liczenie po level: pamięć podąża za rozmiarem wyniku, nie pliku
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl
# średni czas po path: stanem jest stała para {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
| map_values(.total / .count)' app.jsonl
Dwa detale:
-noznacza, że jq nie ma konsumować pierwszego wejścia jako wartości początkowej;inputssamo emituje każdy rekord. Zapomnisz-ni pierwszy rekord zostanie połknięty jako stan początkowy.- Stan reduktora musi mieć stałą postać — tylko liczniki i akumulatory. Gdy tylko wepniesz dopasowane linie do tablicy w reduktorze, pamięć znów rusza z wolumenem danych i strumień nic już nie daje.
Stąd 3,5 MB z tabeli: przepłynęły dwa gigabajty, został tylko tablica haszująca.
Jeden wielki dokument: zdarzenia ścieżek --stream
Gdy wejściem jest jeden ogromny dokument korzeniowy (eksport kilkuset MB bez granic linii), użyj --stream. Zamiast pełnych wartości emituje sekwencję zdarzeń «ścieżka + wartość liścia»:
# zdarzenie wygląda tak: tablica ścieżki + skalar
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"
Wyciąganie ze strumienia zdarzeń wymaga dopasowania pełnego kształtu ścieżki — głębokości, nazw pól, pozycji indeksów — bo sprawdzenie tylko ostatniego składnika złapie też homonimiczne klucze w zagnieżdżonych obiektach:
# tylko rows[i].id, ignorując meta.id i głębszych kuzynów
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json
Agregacja pozostaje reduce inputs o stałej postaci (przy -n --stream zdarzenia trzeba konsumować przez inputs — patrz pułapki). Do rekonstrukcji — zamiany strumienia zdarzeń z powrotem w całe obiekty — łącz truncate_stream i fromstream. Przegląd wyboru narzędzi według rozmiaru jest w Plik JSON za duży?.
Trzy realne pułapki
Pułapka pierwsza: -n --stream bez inputs nie wypisuje niczego, po cichu. Stwierdzone na tej maszynie: jq -n --stream 'select(...)' file.json kończy kodem 0, bez wyjścia i bez błędu — w trybie -n jq nie czyta wejścia, a select filtra nie dostaje ani jednego zdarzenia. Poprawnie: usuń -n i użyj gołego --stream, albo sparuj -n --stream z reduce inputs. Ta klasa awarii «sukces, ale pusto» jest najtrudniejsza do debugowania; waliduj na małej próbce, zanim poskręcasz pipeline.
Pułapka druga: --stream emituje tylko skalarne liście; puste obiekty i tablice nie mają zdarzenia wartości. {"a":{}} wytwarza tylko zdarzenie zamknięcia ścieżki (typu length == 1), a filtr po length == 2 po cichu połknie puste kontenery — zdecyduj wprost, czy liczą się do twoich statystyk.
Pułapka trzecia: wynik częściowy po błędzie parsowania w środku pliku. Strumieniowy pipeline może już wyemitować połowę wyjścia, zanim potknie się o zepsuty JSON pod koniec. jq 1.7 domyślnie pada głośno — [1,] wygenerowało parse error: Expected another array element at line 1, column 4 z kodem 5 w naszym teście — ale jeśli twój shell przekierowuje stdout do pliku docelowego, obcięty wynik już leży na dysku. Inżynierska tarcza: staging plus rename — pisać do pliku tymczasowego i przesunąć na cel dopiero po udanym przebiegu jq. Dla subtelniejszej kontroli --stream-errors zamienia błędy parsowania w zdarzenia, które możesz obsłużyć i jawnie przerwać przez error.
Kiedy nie używać jq: Miller i pipeline hybrydowe
jq to funkcyjny język transformacji drzew, mocny w głębokiej restrukturyzacji. Ale gdy zadanie degeneruje się do «przefiltruj i policz gigabajty płaskich logów», istnieją lepiej dobrane narzędzia. Benchmark dratini.tech na 2,5 GB JSONL (filtr + wybór kolumn):
| Narzędzie | Czas | Szczytowy RSS |
|---|---|---|
| zwykły pipeline jq | 48,2s | 84 MB |
| jq -s | OOM (ubity nawet z 16 GB+) | — |
| Miller (mlr --json) | 11,4s | 18 MB |
| ripgrep + jq hybryda | 8,1s | 32 MB |
Reguła: głębokie zagnieżdżenie, restrukturyzacja, wszechobecność w CI — jq. Płaskie statystyki na gigabajtach, percentyle p95, JSONL do TSV — jedno mlr --json stats1 zastępuje skrypt jq przy stałej pamięci. A jeśli ripgrep potrafi odrzucić 90 % zbędnych linii przed jq, hybryda jest najszybsza.
FAQ
Od jakiego rozmiaru jq -s staje się groźne?
Praktyczny próg: jak tylko plik przekracza połowę dostępnej pamięci, nie ufaj. Pamięć po parsowaniu w typowych przypadkach wartuje 3–10x tekstu (9,5x przy naszych 220 MB; zewnętrzne relacje pokazują plik 4 GB ubijający maszynę 16 GB). Najpierw porównaj ls -lh z free -m i blisko granicy wymień -s na reduce inputs.
Dlaczego -n przed reduce inputs?
-n mówi jq, by nie konsumował pierwszego wejścia jako wartości początkowej programu, żeby inputs samo emitowało każdy rekord. Bez -n pierwszy rekord staje się stanem początkowym reduce i cicho znika z wyniku — utrata danych bez żadnego błędu.
Jak wybrać między --stream a trybem zwykłym?
Najpierw spójrz na postać pliku. JSONL to już strumień linia po linii; --stream nic nie daje. Dla pojedynczego dużego dokumentu, z którego chcesz tylko kilka wartości liści, --stream wymienia około 3x czas na setki razy mniej pamięci. Jeśli plik mieści się w pamięci, zwykłe jq jest po prostu szybsze.
Co zrobić z uszkodzonymi liniami przy strumieniowaniu?
W JSONL fromjson? pomija linie nieprzeparsowalne, żeby jedna brudna linia nie ubiła pipeline. W pojedynczym dużym dokumencie błąd parsowania w środku pliku wywala przebieg — publikuj atomowo przez plik stagingowy i rename, albo użyj --stream-errors dla jawnej kontroli.