Maîtriser les fichiers JSONL : structure, cas d'utilisation et principaux avantages

Un fichier JSONL contient une valeur JSON complète par ligne. La documentation officielle l'appelle « le format texte JSON Lines, également appelé JSON délimité par des sauts de ligne ». Cette règle unique explique pourquoi il se prête bien au streaming, pourquoi il survit aux lectures partielles et pourquoi un tableur ne peut pas l'ouvrir.

Qu'est-ce qu'un fichier JSONL ?

JSON Lines est un format texte pour les enregistrements. La spécification le décrit comme « un format pratique pour stocker des données structurées qui peuvent être traitées un enregistrement à la fois ».

La documentation est explicite quant à son cas d'usage. Il « fonctionne bien avec les outils de traitement de texte de style Unix et les pipelines shell », et la page ajoute que « c'est un excellent format pour les fichiers journaux ». Il est également décrit comme « un format flexible pour transmettre des messages entre processus coopératifs ».

Le contraste avec le JSON classique est tout l'intérêt. Un tableau JSON d'un million d'enregistrements constitue une seule valeur : un lecteur doit tout consommer avant que la structure ne soit complète. Un fichier JSONL d'un million d'enregistrements représente un million de valeurs, et chaque ligne est autonome.

Il existe une seconde spécification très proche. La spécification NDJSON est directe à ce sujet : « il n'existe actuellement aucune norme pour transporter des instances de texte JSON au sein d'un protocole de flux ». Son cas d'usage déclaré est « la diffusion de plusieurs instances de texte JSON via des protocoles de streaming comme TCP ou les pipes UNIX ».

Comment est structuré un fichier JSONL

Les trois exigences

La documentation de JSON Lines en énumère exactement trois. La première est l'encodage UTF-8. Elle s'accompagne d'une mise en garde empruntée à JSON lui-même : « tout comme la norme JSON, une marque d'ordre des octets (BOM, U+FEFF) ne doit PAS être incluse ».

La deuxième est que chaque ligne doit être une valeur JSON valide. La page note que « les valeurs les plus courantes seront des objets ou des tableaux, mais n'importe quelle valeur JSON est autorisée ». Elle présente ensuite le cas particulier qui piège souvent les utilisateurs : « null est une valeur valide, mais une ligne vide ne l'est pas ».

La troisième est que le terminateur de ligne est \n. Les fins de ligne Windows fonctionnent toujours. La raison invoquée est d'ordre mécanique : « cela signifie que \r\n est également pris en charge car les espaces blancs environnants sont implicitement ignorés lors de l'analyse des valeurs JSON ».

Ce qui ne doit pas apparaître à l'intérieur d'une ligne

C'est cette contrainte qui permet au format de fonctionner. La spécification NDJSON l'énonce comme une exigence : « les textes JSON NE DOIVENT PAS contenir de sauts de ligne ou de retours chariot ».

Une valeur JSON est normalement autorisée à s'étendre sur plusieurs lignes grâce à l'indentation. Dans un fichier délimité par des lignes, ce n'est pas possible, car le saut de ligne sert de séparateur d'enregistrements. Chaque enregistrement doit être écrit sur une seule ligne physique.

La ligne finale et les lignes vides

Deux détails diffèrent entre les deux spécifications, et tous deux ont leur importance lorsqu'un fichier est rejeté.

Prenons le saut de ligne final. JSON Lines indique que « l'inclusion d'un terminateur de ligne après la dernière valeur JSON d'un fichier est fortement recommandée mais non obligatoire ».

Sur les lignes vides, les deux spécifications divergent. JSON Lines est strict : une ligne vide n'est pas une valeur valide. NDJSON est permissif, autorisant le fait que « l'analyseur PEUT ignorer silencieusement les lignes vides », tout en exigeant que « ce comportement DOIT être documenté ».

Extensions et types de médias

La dénomination se divise également. JSON Lines indique que les fichiers « peuvent être enregistrés avec l'extension de fichier .jsonl ». Concernant le type de média, il précise que « le type MIME peut être application/jsonl, mais cela n'est pas encore standardisé ». NDJSON indique que le type de média « DEVRAIT être application/x-ndjson » et l'extension « DEVRAIT être .ndjson ».

Pour la compression, JSON Lines recommande des compresseurs de flux : « gzip ou bzip2 sont recommandés pour gagner de l'espace, ce qui donne des fichiers .jsonl.gz ou .jsonl.bz2 ».

Une petite convention mérite d'être connue lorsque vous lisez un message d'erreur. Les éditeurs de texte appellent la première ligne « ligne 1 ». La documentation va plus loin : « la première valeur d'un fichier JSON Lines devrait également être appelée 'valeur 1' ».

À quoi sert le format JSONL

Vous rencontrerez généralement un fichier .jsonl dans l'une de ces quatre situations.

Fichiers de journaux (logs) et d'événements. La propre documentation du format mentionne les fichiers de logs, et la raison en est qu'un programme d'écriture peut ajouter une ligne à la fois sans rien réécrire.

Chargements d'entrepôts de données. La documentation de BigQuery de Google est un bon exemple de la reconnaissance officielle de ce format. Il prend en charge le chargement de « données JSON délimitées par des sauts de ligne (ndJSON) depuis Cloud Storage », et son sélecteur de format de fichier liste l'option sous le nom de « JSONL (Newline delimited JSON) ».

Exports d'API d'enregistrements imbriqués. Les données qui ne s'aplatissent pas proprement en colonnes conservent leur imbrication par ligne. Les lignes de commande avec un nombre variable d'articles en sont l'exemple classique.

Jeux de données d'apprentissage automatique (machine learning). Les ensembles d'entraînement et d'évaluation sont couramment distribués de cette manière, car une boucle d'apprentissage lit les enregistrements un par un.

Le fil conducteur est le streaming. Cela devient le choix évident lorsque le fichier est produit ou consommé de manière incrémentielle.

JSONL contre JSON contre CSV

	JSONL	JSON	CSV
Unité du fichier	Une valeur par ligne	Une valeur pour tout le fichier	Une ligne par ligne
Données imbriquées	Oui, par enregistrement	Oui	Pas nativement
Ajouter un enregistrement	Ajouter une ligne	Réécrire le conteneur	Ajouter une ligne
La lecture partielle est utile	Oui	Rarement	Oui
S'ouvre dans un tableur	Non	Non	Généralement
La structure des enregistrements peut varier	Oui	Oui	Non, les colonnes sont fixes
Lisible par l'humain dans un éditeur	Oui, une longue ligne par enregistrement	Oui, lorsqu'il est indenté	Oui

L'avant-dernière ligne est celle qui surprend le plus. Deux lignes d'un même fichier JSONL peuvent comporter des clés différentes. C'est précisément ce qui rend le format flexible, et c'est exactement pour cela qu'une importation naïve produit des colonnes irrégulières.

Pour l'alternative binaire orientée colonnes, le guide explicatif de Parquet couvre le même sujet du côté du stockage. Pour le cas tabulaire le plus simple, l' analyse du TSV traite du texte séparé par des tabulations.

Principaux avantages

Écriture en ajout uniquement. Un nouvel enregistrement correspond à une nouvelle ligne. Rien de ce qui précède dans le fichier n'a besoin d'être modifié.

Lectures en continu (streaming). Un consommateur peut traiter le premier enregistrement avant même que le deux-millionième n'ait été écrit.

Tolérance aux pannes. Un fichier tronqué reste lisible jusqu'à la dernière ligne complète. Un tableau JSON tronqué est généralement totalement illisible.

Préservation de l'imbrication. La structure qu'un fichier CSV obligerait à aplatir reste intacte au sein de chaque enregistrement.

Adapté au shell. La documentation met en avant le traitement de texte de style Unix et les pipelines shell, car un fichier orienté ligne fonctionne parfaitement avec des outils orientés ligne.

Prise en charge par les entrepôts de données. La documentation de BigQuery énonce la règle qu'elle impose : « chaque objet JSON doit se trouver sur une ligne distincte dans le fichier ».

Les limites du format JSONL

Le format résout les problèmes de transport et d'ajout. Il ne résout aucune des questions que vous vous posez sur le contenu.

La compression est un véritable compromis plutôt qu'un avantage gratuit. La documentation de BigQuery est catégorique sur le coût : « si vous utilisez la compression gzip, BigQuery ne peut pas lire les données en parallèle ». Elle ajoute que « le chargement de données JSON compressées dans BigQuery est plus lent que le chargement de données non compressées ». La propre page du format recommande gzip pour gagner de l'espace. Les deux affirmations sont vraies, et elles vont dans des directions opposées.

Il est également verbeux. Chaque ligne répète chaque nom de clé, de sorte qu'un ensemble d'enregistrements large est nettement plus volumineux que les mêmes données dans un format en colonnes.

De plus, il ne garantit en rien la cohérence. Des enregistrements de structures différentes sont autorisés, ce qui signifie qu'un champ peut discrètement cesser d'apparaître au milieu d'un fichier sans que rien ne soit invalide.

Comment travailler avec un fichier JSONL si vous n'êtes pas un ingénieur

C'est là que se situe le fossé pratique. Les outils professionnels s'attendent à des lignes et des colonnes, et un fichier .jsonl ne s'ouvrira pas de la même manière qu'un CSV.

La voie pragmatique consiste à passer par une étape de conversion. Demandez à la personne qui a généré le fichier un extrait CSV aplati ou Excel des champs dont vous avez besoin. Ou aplatissez-le vous-même à l'aide de n'importe quel outil compatible JSON. Vous perdez l'imbrication, ce qui n'a généralement pas d'importance une fois que vous avez déterminé les champs à utiliser pour l'analyse.

À partir de là, le travail consiste en une analyse ordinaire. La page des tarifs de Powerdrill Bloom répertorie les téléchargements pour Excel, CSV, PDF et documents, de sorte qu'un extrait aplati y est directement intégré. Les questions sont posées en langage naturel plutôt que rédigées sous forme de requêtes. L'assistant IA pour CSV couvre cette approche, et les connecteurs de données couvrent les cas où il est préférable de récupérer les données directement à la source plutôt que de les exporter.

La distinction importante à garder à l'esprit est qu'il s'agit d'une décision de transport prise en amont de votre travail. S'en affranchir par une conversion une fois que le fichier arrive sur votre bureau est une pratique normale, et non une solution de contournement.

Conclusion

Le format JSONL est un format texte régi par une seule règle : une valeur JSON complète par ligne, et aucun saut de ligne à l'intérieur d'une valeur. Cette règle permet l'ajout de données, le streaming et la tolérance aux lectures partielles, ce qui explique pourquoi les fichiers de logs et les chargements d'entrepôts de données l'utilisent par défaut.

Ce qu'il ne permet pas d'obtenir, en revanche, c'est un tableau. Dès que le fichier parvient à quelqu'un qui a besoin de réponses plutôt que d'un pipeline de données, l'étape suivante la plus utile consiste à en faire un extrait aplati et à poser une question.

Si vous en êtes là, essayez Powerdrill Bloom avec le fichier converti et commencez par le transformer en graphique.

Foire aux questions

À quoi sert un fichier JSONL ?

Il est utilisé pour les flux d'enregistrements : fichiers de logs, exports d'événements, chargements d'entrepôts de données et jeux de données d'apprentissage automatique. La documentation du format mentionne spécifiquement les fichiers de logs et les pipelines shell. Le point commun est que les enregistrements sont écrits ou lus un par un.

Quelle est la différence entre JSONL et NDJSON ?

Ils décrivent la même idée avec des formalités différentes. JSON Lines utilise l'extension .jsonl et note que application/jsonl n'est pas encore standardisé. NDJSON spécifie .ndjson et application/x-ndjson, et permet aux analyseurs d'ignorer les lignes vides.

Puis-je ouvrir un fichier JSONL dans Excel ?

Pas en double-cliquant dessus, car chaque ligne est une valeur JSON plutôt qu'une rangée de cellules. L'approche habituelle consiste à aplatir d'abord les champs dont vous avez besoin au format CSV ou Excel, ou à utiliser un outil qui lit directement ce format.

Pourquoi un enregistrement ne peut-il pas s'étendre sur plusieurs lignes en JSONL ?

Parce que le caractère de saut de ligne est le séparateur d'enregistrements. La spécification NDJSON stipule que « les textes JSON NE DOIVENT PAS contenir de sauts de ligne ou de retours chariot ». Le JSON mis en forme de manière lisible (pretty-printed) doit donc être condensé sur une seule ligne par enregistrement.

Une ligne vide est-elle autorisée dans un fichier JSONL ?

Les deux spécifications diffèrent. JSON Lines stipule que « null est une valeur valide, mais une ligne vide ne l'est pas ». NDJSON permet à un analyseur d'ignorer silencieusement les lignes vides, à condition que ce comportement soit documenté.