jq et les gros fichiers JSON : pourquoi -s explose la mémoire et comment écrire en flux
L’essentiel : L'agrégation de centaines de Mo de journaux JSON avec jq -s se termine en OOM, tandis que reduce inputs produit la même statistique en quelques Mo de RAM. Mesuré sur un échantillon de 220 Mo et 2 millions de lignes : slurp culmine à 2,08 Go contre 3,5 Mo pour le réducteur en flux. Cet article explique le mécanisme de consommation mémoire, le traitement ligne à ligne du JSONL, les événements de chemin de --stream et trois pièges réels, dont la sortie vide silencieuse de -n --stream.

jq parse vite, mais presque chaque mort sur un fichier de quelques centaines de Mo remonte au même drapeau :
-scharge toute l'entrée dans un seul tableau géant, et le RSS de pointe atteint facilement plusieurs fois la taille du fichier.
Un fichier, deux requêtes : 580 fois moins de mémoire
Commençons par une mesure. L'échantillon est un journal JSONL de 220 Mo et 2 000 000 de lignes (un enregistrement de requête par ligne : timestamp, level, path, status, duration_ms, uid). Environnement : jq 1.7 sous Linux x86_64, RSS de pointe relevé via /usr/bin/time -v :
| Requête | Tâche | Durée | RSS de pointe |
|---|---|---|---|
jq -s 'group_by(.level) | ...' |
comptage par level | 10,1s | 2,08 Go (~9,5x la taille du fichier) |
jq -n 'reduce inputs ...' |
même comptage | 4,7s | 3,5 Mo |
jq -r 'select(...) | .path' |
filtre ligne à ligne | 2,6s | 3,6 Mo |
Même statistique, 580 fois moins de mémoire, et plus rapide. Ce n'est pas un bug de jq — -s signifie par définition « tout lire dans un tableau » ; la plupart des gens ne chiffrent simplement pas ce coût par défaut. Les chiffres tiers concordent : le retour d'expérience sur 2,3 Go de JSONL de la communauté Huawei Cloud raconte exactement la même histoire — OOM avec slurp, puis le réducteur en flux qui termine en 47 secondes à un peu plus de 30 Mo de RSS. Dratini.tech a mesuré sur 2,5 Go d'entrée un jq -s tué par l'OOM killer même sur une machine de 16 Go+, tandis que le pipeline ordinaire bouclait en 48,2s à 84 Mo.
La conclusion d'abord : si le fichier dépasse la moitié de votre mémoire disponible, -s n'est même pas candidat. Mesurez trois choses avant d'écrire quoi que ce soit : ls -lh pour la taille, free -m pour la marge mémoire, wc -l pour le nombre de lignes.
Où va réellement la mémoire
jq -s (slurp) est documenté comme « lire toutes les entrées dans un tableau ». Le coût réel dépasse largement le texte : après le parsing, jq maintient un arbre de structures C, et chaque objet, tableau, chaîne et nombre porte son propre nœud et ses métadonnées. Nos 220 Mo de texte sont devenus un peu plus de 2 Go de structures — un gonflement d'environ 9,5x. group_by trie et regroupe en plus en mémoire, amplifiant le pic.
Un gros document JSON unique se comporte pareil. En emballant le même journal dans un tableau racine de 300 Mo puis en extrayant avec un filtre ordinaire :
| Requête | Durée | RSS de pointe |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid' (document entier) |
4,7s | 1,85 Go |
jq --stream 'select(...)' (événements de chemin) |
13,4s | 3,4 Mo |
Le parsing intégral culmine encore autour de 1,8 Go — jq construit tout l'arbre avant que le filtre ne s'exécute. --stream échange environ 3x le temps d'exécution contre une mémoire 540 fois plus petite. Le modèle détaillé de ce gonflement est développé dans D'où vient la mémoire.
Journaux JSONL : la lecture ligne à ligne est déjà du flux
Si votre « gros fichier » est en réalité du JSONL — un objet par ligne — le comportement par défaut de jq est déjà un flux : chaque ligne est parsée et émise indépendamment, et -s n'est pas seulement inutile, il est nuisible :
# comptage par level : ligne à ligne, agrégation dans le shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head
# filtre + extraction : select en premier, les lignes non concordantes sont jetées aussitôt
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5
Deux habitudes à forcer :
selectau tout début du pipeline. jq filtre dès qu'une ligne est parsée ; filtrer après les transformations gaspille le calcul.-rpour des chaînes brutes. Sans lui, la sortie est une chaîne JSON quotée, etuniq -ccomptera"ERROR"etERRORcomme deux valeurs distinctes.
Pour les lignes corrompues, utilisez fromjson? : jq -r 'fromjson? | .level' saute silencieusement les lignes non parsables, et un fragment tronqué ne tue pas tout le pipeline. Le format lui-même est traité dans Le manuel pratique JSONL ; cet article concerne les commandes qui le traitent.
Agrégation globale : reduce inputs garde l'état borné
Le filtrage ligne à ligne appartient au shell, mais quand l'agrégation doit se faire dans jq — compteurs par level, durée moyenne par path —, la clé est reduce avec inputs, pour un état borné :
# comptage par level : la mémoire suit la taille du résultat, pas du fichier
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl
# durée moyenne par path : l'état est une paire fixe {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
| map_values(.total / .count)' app.jsonl
Deux détails :
-nsignifie que jq ne doit pas consommer la première entrée comme valeur initiale ;inputsémet chaque enregistrement lui-même. Oublier-net le premier enregistrement est avalé comme état initial.- L'état du réducteur doit être de forme fixe — compteurs et accumulateurs seulement. Dès que vous poussez les lignes correspondantes dans un tableau dans le réducteur, la mémoire repart avec le volume de données et le flux ne sert plus à rien.
D'où les 3,5 Mo du tableau : deux gigaoctets sont passés, il ne reste qu'une table de hachage.
Un seul gros document : les événements de chemin de --stream
Quand l'entrée est un seul énorme document racine (un export de quelques centaines de Mo sans frontières de lignes), utilisez --stream. Au lieu de valeurs complètes, il émet une séquence d'événements « chemin + valeur feuille » :
# un événement ressemble à : tableau de chemin + scalaire
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"
Extraire du flux d'événements impose d'apparier la forme complète du chemin — profondeur, noms de membres, positions d'indices — car ne vérifier que le dernier composant attrapera aussi les clés homonymes dans les objets imbriqués :
# seulement rows[i].id, en ignorant meta.id et les homonymes plus profonds
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json
L'agrégation reste le reduce inputs de forme fixe (avec -n --stream, les événements doivent être consommés via inputs — voir les pièges). Pour la reconstitution — transformer un flux d'événements en objets entiers — combinez truncate_stream et fromstream. La vue d'ensemble du choix d'outils par taille est dans Fichier JSON trop gros ?.
Trois pièges réels
Piège un : -n --stream sans inputs sort silencieusement rien. Constaté sur cette machine : jq -n --stream 'select(...)' file.json se termine avec le code 0, sans sortie ni erreur — en mode -n, jq ne lit pas l'entrée, et le select du filtre ne reçoit aucun événement. Correct : enlever -n et utiliser --stream nu, ou coupler -n --stream avec reduce inputs. Cette classe d'échecs « succès mais vide » est la plus difficile à déboguer ; validez sur un petit échantillon avant de câbler un pipeline.
Piège deux : --stream n'émet que des feuilles scalaires ; les objets et tableaux vides n'ont pas d'événement de valeur. {"a":{}} ne produit qu'un événement de fermeture de chemin (le genre length == 1), et un filtre sur length == 2 avalera silencieusement les conteneurs vides — décidez explicitement s'ils comptent dans vos statistiques.
Piège trois : résultat partiel après un parse error en milieu de fichier. Un pipeline en flux peut avoir déjà émis la moitié de sa sortie avant de buter sur du JSON cassé vers la fin. jq 1.7 échoue bruyamment par défaut — [1,] a produit parse error: Expected another array element at line 1, column 4 avec le code 5 dans notre test — mais si votre shell redirige stdout vers le fichier cible, le résultat tronqué est déjà sur disque. La parade d'ingénierie : staging plus rename — écrire dans un fichier temporaire et mv par-dessus la cible seulement après le succès de jq. Pour un contrôle plus fin, --stream-errors transforme les erreurs de parsing en événements que vous pouvez traiter et interrompre explicitement via error.
Quand ne pas utiliser jq : Miller et les pipelines hybrides
jq est un langage fonctionnel de transformation d'arbres, fort en restructuration profonde. Mais dès que la tâche dégénère en « filtrer et compter des gigaoctets de journaux plats », des outils mieux taillés existent. Le benchmark de dratini.tech sur 2,5 Go de JSONL (filtre + sélection de colonnes) :
| Outil | Durée | RSS de pointe |
|---|---|---|
| jq pipeline ordinaire | 48,2s | 84 Mo |
| jq -s | OOM (tué même avec 16 Go+) | — |
| Miller (mlr --json) | 11,4s | 18 Mo |
| ripgrep + jq hybride | 8,1s | 32 Mo |
La règle : imbrication profonde, restructuration, omniprésence en CI — jq. Statistiques plates multi-gigaoctets, percentiles p95, JSONL vers TSV — un seul mlr --json stats1 remplace un script jq à mémoire constante. Et si ripgrep peut éliminer 90 % des lignes inutiles avant jq, l'hybride est le plus rapide.
FAQ
À partir de quelle taille jq -s devient-il dangereux ?
Seuil pratique : dès que le fichier dépasse la moitié de la mémoire disponible, méfiance. La mémoire après parsing vaut typiquement 3 à 10 fois le texte (9,5x sur nos 220 Mo ; des retours tiers montrent un fichier de 4 Go tuer une machine de 16 Go). Comparez d'abord ls -lh et free -m, et remplacez -s par reduce inputs si c'est proche.
Pourquoi -n devant reduce inputs ?
-n dit à jq de ne pas consommer la première entrée comme valeur initiale du programme, pour que inputs émette lui-même chaque enregistrement. Sans -n, le premier enregistrement devient l'état initial du reduce et disparaît silencieusement du résultat — une perte de données sans aucune erreur.
Comment choisir entre --stream et le mode ordinaire ?
Regardez d'abord la forme du fichier. Le JSONL est déjà un flux ligne à ligne ; --stream ne sert à rien. Pour un seul gros document dont vous ne voulez que quelques valeurs feuilles, --stream échange environ 3x le temps contre des centaines de fois moins de mémoire. Si le fichier tient en mémoire, le jq ordinaire est simplement plus rapide.
Que faire des lignes corrompues en flux ?
En JSONL, fromjson? saute les lignes imparsables pour qu'une seule ligne sale ne tue pas le pipeline. Dans un gros document unique, un parse error en milieu de fichier fait échouer l'exécution — publiez atomiquement via un fichier de staging et un rename, ou utilisez --stream-errors pour un contrôle explicite.