JSON Toolkit

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.

Zaawansowany~6 min czytaniaOpublikowano 2026-11-12Zaktualizowano 2026-11-12
Porównanie pamięci między strumieniowym jq a -s na dużych JSON-ach

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:

  • select na samym początku pipeline. jq filtruje, jak tylko linia jest sparsowana; filtrowanie po transformacjach marnuje obliczenia.
  • -r dla surowych stringów. Bez niego wyjściem jest cudzysłowowany string JSON, a uniq -c policzy "ERROR" i ERROR jako 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:

  • -n oznacza, że jq nie ma konsumować pierwszego wejścia jako wartości początkowej; inputs samo emituje każdy rekord. Zapomnisz -n i 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.