jq und große JSON-Dateien: Warum -s den Speicher sprengt und wie man streamt
Fazit: Die Aggregation von Hunderten MB JSON-Logs mit jq -s endet im OOM, während reduce inputs dieselbe Statistik mit wenigen MB RAM erzeugt. Gemessen an einer 220-MB-Stichprobe mit 2 Millionen Zeilen: slurp gipfelt bei 2,08 GB gegenüber 3,5 MB für den Streaming-Reducer. Dieser Artikel erklärt den Speichermechanismus, die zeilenweise JSONL-Verarbeitung, die Pfadereignisse von --stream und drei echte Fallstricke, darunter die stille Leer-Ausgabe von -n --stream.

jq parst schnell, aber fast jeder Ausfall an einer Datei von ein paar Hundert MB führt auf dasselbe Flag zurück:
-slädt die gesamte Eingabe in ein einziges riesiges Array, und der Spitzen-RSS erreicht leicht ein Vielfaches der Dateigröße.
Eine Datei, zwei Abfragen: 580-mal weniger Speicher
Beginnen wir mit einer Messung. Die Stichprobe ist ein JSONL-Log von 220 MB und 2.000.000 Zeilen (ein Request-Datensatz pro Zeile: timestamp, level, path, status, duration_ms, uid). Umgebung: jq 1.7 unter Linux x86_64, Spitzen-RSS erfasst via /usr/bin/time -v:
| Abfrage | Aufgabe | Dauer | Spitzen-RSS |
|---|---|---|---|
jq -s 'group_by(.level) | ...' |
Zählung nach level | 10,1s | 2,08 GB (~9,5x Dateigröße) |
jq -n 'reduce inputs ...' |
dieselbe Zählung | 4,7s | 3,5 MB |
jq -r 'select(...) | .path' |
Filter zeilenweise | 2,6s | 3,6 MB |
Dieselbe Statistik, 580-mal weniger Speicher, und obendrein schneller. Das ist kein jq-Bug — -s bedeutet per Definition „alles in ein Array lesen"; die meisten Menschen schätzen diesen Standardkosten einfach nicht richtig ein. Drittquellen bestätigen das Bild: der Erfahrungsbericht über 2,3 GB JSONL aus der Huawei-Cloud-Community erzählt exakt dieselbe Geschichte — OOM mit slurp, dann der Streaming-Reducer, der in 47 Sekunden bei gut 30 MB RSS fertig wird. Dratini.tech hat bei 2,5 GB Eingabe einen jq -s vom OOM-Killer getötet gesehen, selbst auf einer Maschine mit 16 GB+, während die gewöhnliche Pipeline in 48,2s bei 84 MB durchlief.
Die Schlussfolgerung vorweg: Wenn die Datei mehr als die Hälfte des verfügbaren Speichers beansprucht, ist -s gar kein Kandidat. Messen Sie drei Dinge, bevor Sie irgendetwas schreiben: ls -lh für die Größe, free -m für die Speichermarge, wc -l für die Zeilenzahl.
Wohin der Speicher wirklich geht
jq -s (slurp) ist dokumentiert als „alle Eingaben in ein Array lesen". Die realen Kosten übersteigen den Text bei Weitem: Nach dem Parsen hält jq einen Baum aus C-Strukturen, und jedes Objekt, Array, jeder String und jede Zahl trägt seinen eigenen Knoten samt Metadaten. Unsere 220 MB Text wurden ein wenig über 2 GB Strukturen — eine Aufblähung von etwa 9,5x. group_by sortiert und gruppiert zusätzlich im Speicher und verstärkt den Peak.
Ein einzelnes großes JSON-Dokument verhält sich genauso. Beim Verpacken desselben Logs in ein 300-MB-Root-Array und Extrahieren mit einem gewöhnlichen Filter:
| Abfrage | Dauer | Spitzen-RSS |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid' (gesamtes Dokument) |
4,7s | 1,85 GB |
jq --stream 'select(...)' (Pfadereignisse) |
13,4s | 3,4 MB |
Das Vollparsen gipfelt weiterhin bei rund 1,8 GB — jq baut den ganzen Baum auf, bevor der Filter läuft. --stream tauscht etwa die dreifache Laufzeit gegen 540-mal weniger Speicher. Das detaillierte Modell dieser Aufblähung wird in Woher kommt der Speicher entwickelt.
JSONL-Logs: Zeilenweises Lesen ist bereits Streaming
Wenn Ihre „große Datei" in Wahrheit JSONL ist — ein Objekt pro Zeile —, ist das Standardverhalten von jq bereits ein Stream: Jede Zeile wird unabhängig geparst und ausgegeben, und -s ist nicht nur unnötig, sondern schädlich:
# Zählung nach level: zeilenweise, Aggregation in der Shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head
# Filter + Extraktion: select zuerst, nicht passende Zeilen werden sofort verworfen
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5
Zwei Gewohnheiten, die man sich antrainieren sollte:
selectganz am Anfang der Pipeline. jq filtert, sobald eine Zeile geparst ist; nach den Transformationen zu filtern verschwendet Rechenarbeit.-rfür rohe Strings. Ohne ihn ist die Ausgabe ein quotierter JSON-String, unduniq -czählt"ERROR"undERRORals zwei verschiedene Werte.
Für kaputte Zeilen nutzen Sie fromjson?: jq -r 'fromjson? | .level' überspringt nicht parsbare Zeilen stillschweigend, und ein abgeschnittenes Fragment bringt nicht die ganze Pipeline zu Fall. Das Format selbst behandelt Das JSONL-Praxisbuch; hier geht es um die Befehle, die es verarbeiten.
Globale Aggregation: reduce inputs hält den Zustand begrenzt
Das zeilenweise Filtern gehört in die Shell, aber wenn die Aggregation in jq selbst stattfinden muss — Zähler nach level, mittlere Dauer pro path —, ist der Schlüssel reduce mit inputs, für einen begrenzten Zustand:
# Zählung nach level: der Speicher folgt der Ergebnisgröße, nicht der Dateigröße
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl
# mittlere Dauer pro path: der Zustand ist ein festes Paar {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
| map_values(.total / .count)' app.jsonl
Zwei Details:
-nbedeutet, dass jq nicht die erste Eingabe als Anfangswert konsumiert;inputsgibt jeden Datensatz selbst aus. Vergisst man-n, wird der erste Datensatz als Anfangszustand verschlungen.- Der Reducer-Zustand muss eine feste Form haben — nur Zähler und Akkumulatoren. Sobald Sie die passenden Zeilen in ein Array im Reducer schieben, wächst der Speicher wieder mit dem Datenvolumen, und das Streaming ist wertlos.
Daher die 3,5 MB in der Tabelle: Zwei Gigabyte sind durchgelaufen, übrig bleibt nur eine Hashtabelle.
Ein einziges großes Dokument: die Pfadereignisse von --stream
Wenn die Eingabe ein einziges riesiges Root-Dokument ist (ein Export von ein paar Hundert MB ohne Zeilengrenzen), verwenden Sie --stream. Statt vollständiger Werte gibt er eine Sequenz von „Pfad + Blattwert"-Ereignissen aus:
# ein Ereignis sieht so aus: Pfad-Array + Skalar
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"
Die Extraktion aus dem Ereignisstrom erfordert, die vollständige Pfadform abzugleichen — Tiefe, Membernamen, Indexpositionen —, denn nur die letzte Komponente zu prüfen, erwischt auch gleichnamige Schlüssel in verschachtelten Objekten:
# nur rows[i].id, unter Ignorierung von meta.id und tieferen Namensvettern
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json
Die Aggregation bleibt das reduce inputs fester Form (bei -n --stream müssen die Ereignisse über inputs konsumiert werden — siehe Fallstricke). Für die Rekonstruktion — einen Ereignisstrom zurück in ganze Objekte verwandeln — kombinieren Sie truncate_stream und fromstream. Die Größenübersicht der Werkzeugwahl finden Sie in JSON-Datei zu groß?.
Drei echte Fallstricke
Fallstrick eins: -n --stream ohne inputs gibt still nichts aus. Auf dieser Maschine festgestellt: jq -n --stream 'select(...)' file.json endet mit Code 0, ohne Ausgabe oder Fehler — im -n-Modus liest jq die Eingabe nicht, und das select des Filters erhält kein einziges Ereignis. Richtig: -n weglassen und pures --stream nutzen, oder -n --stream mit reduce inputs koppeln. Diese Klasse von „erfolgreich, aber leer"-Fehlern ist am schwersten zu debuggen; validieren Sie an einer kleinen Stichprobe, bevor Sie eine Pipeline verdrahten.
Fallstrick zwei: --stream gibt nur skalare Blätter aus; leere Objekte und Arrays haben kein Wertereignis. {"a":{}} erzeugt nur ein Pfad-Schließ-Ereignis (die Sorte mit length == 1), und ein Filter auf length == 2 schluckt leere Container stillschweigend — entscheiden Sie explizit, ob sie in Ihre Statistik gehören.
Fallstrick drei: Teilergebnis nach einem Parse-Fehler mitten in der Datei. Eine Streaming-Pipeline kann die Hälfte ihrer Ausgabe bereits ausgegeben haben, bevor sie am Ende auf kaputtes JSON stößt. jq 1.7 scheitert standardmäßig laut — [1,] erzeugte in unserem Test parse error: Expected another array element at line 1, column 4 mit Code 5 —, aber wenn Ihre Shell stdout in die Zieldatei umleitet, liegt das verstümmelte Ergebnis bereits auf der Platte. Der ingenieurmäßige Schutz: Staging plus Rename — in eine temporäre Datei schreiben und erst nach erfolgreichem jq-Durchlauf per mv über das Ziel legen. Für feinere Kontrolle macht --stream-errors aus Parse-Fehlern Ereignisse, die Sie behandeln und per error explizit abbrechen können.
Wann man jq nicht benutzt: Miller und hybride Pipelines
jq ist eine funktionale Sprache zur Baum-Transformation, stark in tiefer Umstrukturierung. Sobald die Aufgabe aber zu „GB von flachen Logs filtern und zählen" verkümmert, gibt es besser passende Werkzeuge. Der dratini.tech-Benchmark über 2,5 GB JSONL (Filter + Spaltenauswahl):
| Werkzeug | Dauer | Spitzen-RSS |
|---|---|---|
| gewöhnliche jq-Pipeline | 48,2s | 84 MB |
| jq -s | OOM (getötet selbst mit 16 GB+) | — |
| Miller (mlr --json) | 11,4s | 18 MB |
| ripgrep + jq hybrid | 8,1s | 32 MB |
Die Regel: tiefe Verschachtelung, Umstrukturierung, Allgegenwart in CI — jq. Flache Multi-Gigabyte-Statistiken, p95-Perzentile, JSONL nach TSV — ein einziges mlr --json stats1 ersetzt ein jq-Skript bei konstantem Speicher. Und wenn ripgrep 90 % der unnötigen Zeilen vor jq aussortieren kann, ist der Hybrid am schnellsten.
FAQ
Ab welcher Größe wird jq -s gefährlich?
Praktische Schwelle: Sobald die Datei mehr als die Hälfte des verfügbaren Speichers beansprucht, Vorsicht. Der Speicher nach dem Parsen liegt typischerweise beim 3- bis 10-Fachen des Textes (9,5x bei unseren 220 MB; Drittberichte zeigen eine 4-GB-Datei, die eine 16-GB-Maschine tötet). Vergleichen Sie zuerst ls -lh mit free -m und ersetzen Sie -s nahe an der Grenze durch reduce inputs.
Warum -n vor reduce inputs?
-n sagt jq, nicht die erste Eingabe als Anfangswert des Programms zu konsumieren, damit inputs selbst jeden Datensatz ausgibt. Ohne -n wird der erste Datensatz zum Anfangszustand des Reduce und verschwindet stillschweigend aus dem Ergebnis — ein Datenverlust ohne jede Fehlermeldung.
Wie wählt man zwischen --stream und dem gewöhnlichen Modus?
Schauen Sie zuerst auf die Form der Datei. JSONL ist bereits ein zeilenweiser Stream; --stream nützt nichts. Bei einem einzelnen großen Dokument, aus dem Sie nur wenige Blattwerte wollen, tauscht --stream etwa die dreifache Zeit gegen Hundertfache weniger Speicher. Passt die Datei in den Speicher, ist gewöhnliches jq einfach schneller.
Was tun mit kaputten Zeilen beim Streaming?
In JSONL überspringt fromjson? unparbare Zeilen, damit eine einzige schmutzige Zeile die Pipeline nicht tötet. In einem einzelnen großen Dokument lässt ein Parse-Fehler mitten in der Datei den Lauf scheitern — veröffentlichen Sie atomar über Staging-Datei und Rename, oder nutzen Sie --stream-errors für explizite Kontrolle.