JSON Toolkit

jq e file JSON di grandi dimensioni: perché -s esplode la memoria e come scrivere in streaming

In sintesi: L'aggregazione di centinaia di MB di log JSON con jq -s finisce in OOM, mentre reduce inputs produce la stessa statistica con pochi MB di RAM. Misurato su un campione da 220 MB e 2 milioni di righe: slurp culmina a 2,08 GB contro 3,5 MB del riduttore in streaming. Questo articolo spiega il meccanismo del consumo di memoria, l'elaborazione riga per riga del JSONL, gli eventi di percorso di --stream e tre insidie reali, compreso l'output vuoto silenzioso di -n --stream.

Avanzato~6 min di letturaPubblicato il 2026-11-12Aggiornato il 2026-11-12
Confronto di memoria tra streaming jq e -s su JSON di grandi dimensioni

jq parses velocemente, ma quasi ogni morte su un file di qualche centinaio di MB risale allo stesso flag: -s carica l'intero input in un unico array gigantesco, e l'RSS di picco raggiunge facilmente diverse volte la dimensione del file.

Un file, due query: 580 volte meno memoria

Cominciamo con una misurazione. Il campione è un log JSONL da 220 MB e 2.000.000 di righe (un record di richiesta per riga: timestamp, level, path, status, duration_ms, uid). Ambiente: jq 1.7 su Linux x86_64, RSS di picco rilevato tramite /usr/bin/time -v:

Query Compito Durata RSS di picco
jq -s 'group_by(.level) | ...' conteggio per level 10,1s 2,08 GB (~9,5x la dimensione del file)
jq -n 'reduce inputs ...' lo stesso conteggio 4,7s 3,5 MB
jq -r 'select(...) | .path' filtro riga per riga 2,6s 3,6 MB

La stessa statistica, 580 volte meno memoria, e pure più veloce. Non è un bug di jq — -s significa per definizione «leggere tutto in un array»; la maggior parte delle persone semplicemente non quantifica questo costo predefinito. Le fonti di terzi concordano: l'esperienza su 2,3 GB di JSONL della community Huawei Cloud racconta esattamente la stessa storia — OOM con slurp, poi il riduttore in streaming che termina in 47 secondi a poco più di 30 MB di RSS. Dratini.tech ha misurato su 2,5 GB di input un jq -s ucciso dall'OOM killer persino su una macchina con oltre 16 GB, mentre la pipeline ordinaria completava in 48,2s con 84 MB.

La conclusione prima di tutto: se il file supera metà della memoria disponibile, -s non è nemmeno un candidato. Misura tre cose prima di scrivere qualsiasi cosa: ls -lh per la dimensione, free -m per il margine di memoria, wc -l per il numero di righe.

Dove va realmente la memoria

jq -s (slurp) è documentato come «leggere tutti gli input in un array». Il costo reale supera ampiamente il testo: dopo il parsing, jq mantiene un albero di strutture C, e ogni oggetto, array, stringa e numero porta il proprio nodo con i metadati. I nostri 220 MB di testo sono diventati poco più di 2 GB di strutture — un gonfiore di circa 9,5x. group_by inoltre ordina e raggruppa in memoria, amplificando il picco.

Un singolo documento JSON grande si comporta allo stesso modo. Confezionando lo stesso log in un array radice da 300 MB ed estraendo con un filtro ordinario:

Query Durata RSS di picco
jq '.[] | select(.level=="ERROR") | .uid' (documento intero) 4,7s 1,85 GB
jq --stream 'select(...)' (eventi di percorso) 13,4s 3,4 MB

Il parsing integrale culmina ancora intorno a 1,8 GB — jq costruisce tutto l'albero prima che il filtro venga eseguito. --stream scambia circa 3 volte il tempo di esecuzione con una memoria 540 volte minore. Il modello dettagliato di questo gonfiore è sviluppato in Da dove viene la memoria.

Log JSONL: la lettura riga per riga è già streaming

Se il tuo «file grande» in realtà è JSONL — un oggetto per riga —, il comportamento predefinito di jq è già un flusso: ogni riga viene parses ed emessa in modo indipendente, e -s non è solo inutile, è dannoso:

# conteggio per level: riga per riga, aggregazione nella shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# filtro + estrazione: select per primo, le righe non corrispondenti vengono scartate subito
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

Due abitudini da imporre:

  • select all'inizio della pipeline. jq filtra appena una riga viene parses; filtrare dopo le trasformazioni spreca calcolo.
  • -r per stringhe grezze. Senza di esso, l'output è una stringa JSON tra virgolette, e uniq -c conterà "ERROR" ed ERROR come due valori distinti.

Per le righe corrotte usa fromjson?: jq -r 'fromjson? | .level' salta silenziosamente le righe non parses, e un frammento troncato non uccide tutta la pipeline. Il formato in sé è trattato in Il manuale pratico JSONL; questo articolo riguarda i comandi che lo elaborano.

Aggregazione globale: reduce inputs mantiene lo stato limitato

Il filtraggio riga per riga appartiene alla shell, ma quando l'aggregazione deve avvenire dentro jq — contatori per level, durata media per path —, la chiave è reduce con inputs, per uno stato limitato:

# conteggio per level: la memoria segue la dimensione del risultato, non quella del file
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# durata media per path: lo stato è una coppia fissa {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

Due dettagli:

  • -n significa che jq non deve consumare il primo input come valore iniziale; inputs emette ogni record da sé. Dimenticare -n e il primo record viene inghiottito come stato iniziale.
  • Lo stato del riduttore deve avere forma fissa — solo contatori e accumulatori. Appena spingi le righe corrispondenti in un array dentro il riduttore, la memoria riparte con il volume dei dati e lo streaming non serve più a nulla.

Da qui i 3,5 MB della tabella: sono passati due gigabyte, resta solo una tabella hash.

Un unico grande documento: gli eventi di percorso di --stream

Quando l'input è un unico enorme documento radice (un export di qualche centinaio di MB senza confini di riga), usa --stream. Invece di valori completi, emette una sequenza di eventi «percorso + valore foglia»:

# un evento appare così: array di percorso + scalare
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

Estrarre dal flusso di eventi impone di abbinare la forma completa del percorso — profondità, nomi dei membri, posizioni degli indici — perché controllare solo l'ultimo componente catturerà anche chiavi omonime negli oggetti annidati:

# solo rows[i].id, ignorando meta.id e gli omonimi più profondi
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

L'aggregazione resta il reduce inputs a forma fissa (con -n --stream, gli eventi devono essere consumati via inputs — vedi le insidie). Per la ricostruzione — trasformare un flusso di eventi di nuovo in oggetti interi — combina truncate_stream e fromstream. La panoramica della scelta degli strumenti per dimensione è in File JSON troppo grande?.

Tre insidie reali

Insidia uno: -n --stream senza inputs non produce nulla, in silenzio. Constatare su questa macchina: jq -n --stream 'select(...)' file.json termina con codice 0, senza output né errore — in modalità -n, jq non legge l'input, e il select del filtro non riceve alcun evento. Corretto: togliere -n e usare --stream puro, o accoppiare -n --stream con reduce inputs. Questa classe di fallimenti «successo ma vuoto» è la più difficile da debuggare; valida su un piccolo campione prima di cablare una pipeline.

Insidia due: --stream emette solo foglie scalari; gli oggetti e gli array vuoti non hanno un evento di valore. {"a":{}} produce solo un evento di chiusura di percorso (del tipo length == 1), e un filtro su length == 2 inghiottirà silenziosamente i contenitori vuoti — decidi esplicitamente se contano nelle tue statistiche.

Insidia tre: risultato parziale dopo un errore di parsing a metà file. Una pipeline in streaming può aver già emesso metà del suo output prima di urtare del JSON rotto verso la fine. jq 1.7 fallisce rumorosamente per impostazione predefinita — [1,] ha prodotto parse error: Expected another array element at line 1, column 4 con codice 5 nel nostro test — ma se la tua shell reindirizza stdout verso il file di destinazione, il risultato troncato è già su disco. La parata ingegneristica: staging più rename — scrivere in un file temporaneo e spostare sopra la destinazione solo dopo il successo di jq. Per un controllo più fine, --stream-errors trasforma gli errori di parsing in eventi che puoi trattare e interrompere esplicitamente via error.

Quando non usare jq: Miller e le pipeline ibride

jq è un linguaggio funzionale di trasformazione di alberi, forte nella ristrutturazione profonda. Ma appena il compito degenera in «filtrare e contare gigabyte di log piatti», esistono strumenti più adatti. Il benchmark di dratini.tech su 2,5 GB di JSONL (filtro + selezione di colonne):

Strumento Durata RSS di picco
pipeline jq ordinaria 48,2s 84 MB
jq -s OOM (ucciso persino con 16 GB+) —
Miller (mlr --json) 11,4s 18 MB
ripgrep + jq ibrido 8,1s 32 MB

La regola: annidamento profondo, ristrutturazione, onnipresenza in CI — jq. Statistiche piatte multigigabyte, percentili p95, JSONL verso TSV — un solo mlr --json stats1 sostituisce uno script jq con memoria costante. E se ripgrep può eliminare il 90 % delle righe inutili prima di jq, l'ibrido è il più veloce.

FAQ

Da quale dimensione jq -s diventa pericoloso?

Soglia pratica: appena il file supera metà della memoria disponibile, diffida. La memoria dopo il parsing vale tipicamente da 3 a 10 volte il testo (9,5x sui nostri 220 MB; report di terzi mostrano un file da 4 GB che uccide una macchina da 16 GB). Confronta prima ls -lh con free -m e sostituisci -s con reduce inputs se sei vicino al limite.

Perché -n davanti a reduce inputs?

-n dice a jq di non consumare il primo input come valore iniziale del programma, così che inputs emetta lui stesso ogni record. Senza -n, il primo record diventa lo stato iniziale del reduce e sparisce silenziosamente dal risultato — una perdita di dati senza alcun errore.

Come scegliere tra --stream e la modalità ordinaria?

Guarda prima la forma del file. Il JSONL è già un flusso riga per riga; --stream non serve a nulla. Per un unico documento grande di cui vuoi solo alcuni valori foglia, --stream scambia circa 3 volte il tempo con centinaia di volte meno memoria. Se il file sta in memoria, il jq ordinario è semplicemente più veloce.

Cosa fare con le righe corrotte in streaming?

In JSONL, fromjson? salta le righe imparsevoli perché una sola riga sporca non uccida la pipeline. In un unico grande documento, un errore di parsing a metà file fa fallire l'esecuzione — pubblica atomicamente tramite file di staging e rename, o usa --stream-errors per un controllo esplicito.