Convertir JSON en NDJSON

C’est tout le mécanisme, et cela mérite d’être dit avant toute autre chose. Si le document est un tableau, chaque élément devient une ligne. Si c’est autre chose — un objet, une chaîne, un nombre — le document entier devient une seule ligne, parce que NDJSON se définit comme une valeur JSON complète par ligne et qu’un objet unique est une seule valeur.

Aucun des deux cas n’est une erreur, et le convertisseur ne vous préviendra pas, donc la vérification vous incombe : ouvrez le fichier et regardez le premier caractère. Un crochet carré produit le fichier que vous vouliez. Une accolade produit une seule très longue ligne, qui est du NDJSON valide, qui se charge sans protester dans la plupart des consommateurs, et qui représente un enregistrement là où vous en attendiez des milliers.

Les réponses d’API ne sont presque jamais un tableau brut. Elles prennent la forme d’un objet ayant une clé — data, results, items, records — dont la valeur est le tableau. Pour les conversions tabulaires de ce site, cette enveloppe est retirée automatiquement, parce qu’un tableau n’a nulle part où la mettre. Sur cette paire, elle ne l’est pas, et la différence prend les gens de court.

La raison en est que l’enveloppe est ici un enregistrement légitime. NDJSON peut contenir des objets de n’importe quelle forme, si bien qu’il n’y a aucun moyen de distinguer « une enveloppe à jeter » d’un « enregistrement qui se trouve contenir une liste », et deviner reviendrait à supprimer silencieusement des données sur les fichiers où la devinette est fausse. La correction est une édition de dix secondes dans un éditeur de texte : supprimez l’accolade ouvrante et la clé, supprimez l’accolade fermante, enregistrez, convertissez. Si vous le faites souvent, jq avec l’expression .data fait la même chose sans ouvrir le fichier.

Toute autre cible pour un export JSON sur ce site doit aplatir. Un CSV, un TSV, un ordre SQL d’insertion ou une colonne Parquet n’a nulle part où mettre un objet à l’intérieur d’une valeur, donc l’imbrication devient des noms de colonnes pointés et les tableaux deviennent des colonnes numérotées. NDJSON n’a pas ce problème : chaque ligne est du JSON, de sorte qu’une commande portant une adresse client imbriquée et cinq lignes d’articles arrive intacte.

C’est ce qui fait de cette conversion le bon choix quand la structure est la donnée. Si la destination sait lire du JSON délimité par des sauts de ligne — et c’est le cas de la plupart des outils de chargement en entrepôt, des producteurs de files et des expéditeurs de journaux — vous obtenez les propriétés de streaming et de comptage de lignes sans rien payer en structure. Les conversions qui aplatissent sont pour les destinations qui ne peuvent vraiment pas contenir un arbre.

Chaque enregistrement est écrit de manière compacte : pas d’indentation, pas de sauts de ligne à l’intérieur d’un enregistrement, une ligne par élément sans espace superflu. Si la source était joliment indentée, le fichier devient nettement plus petit sans que rien n’ait été supprimé, parce qu’un export JSON formaté est souvent plus d’espaces que de données.

L’ordre des clés dans chaque enregistrement est préservé, et aucune clé n’est ajoutée ni retirée. Un enregistrement qui manquait d’un champ dans le tableau le manque aussi sur sa ligne — NDJSON ne réconcilie pas les enregistrements entre eux comme le font les écritures tabulaires, et n’en a pas besoin, puisqu’il n’y a pas d’en-tête partagé à remplir.

Un saut de ligne à l’intérieur d’une valeur de chaîne est neutralisé dans le JSON, et non écrit littéralement, de sorte que rien dans les données ne peut produire de rupture de ligne. C’est ce qui fait de la limite de ligne une véritable garantie plutôt qu’une convention : wc -l donne le nombre d’enregistrements, split -l 50000 produit des morceaux valides, et head -1 montre un enregistrement complet.

Cela change aussi ce que coûte un fichier cassé. Un tableau JSON malformé ne donne rien — l’analyse échoue et vous ne pouvez pas dire quel enregistrement était en cause. Une ligne malformée dans un fichier NDJSON vous coûte cette ligne, et le convertisseur qui la relira nommera le numéro de ligne, ce qui est la différence entre une correction de cinq minutes et un après-midi passé avec un éditeur hexadécimal.

Il y a une ironie qu’il vaut la peine d’assumer sur cette paire. Tout l’intérêt de NDJSON est qu’un consommateur n’a jamais à tenir le fichier entier, et le produire ici exige exactement cela : un tableau JSON n’est valide qu’à l’arrivée de son crochet fermant, si bien que le document est analysé en entier avant que la première ligne puisse être écrite.

La limite pratique est donc votre propre mémoire plutôt qu’un seuil de taille, et un document de plusieurs centaines de mégaoctets est là où un onglet de navigateur commence à peiner. Si c’est vous qui produisez les données, la bonne correction se fait en amont — faites en sorte que la source émette directement du NDJSON, ce qui est un changement d’une ligne dans la plupart des exportateurs et qui retire l’analyse du fichier entier du pipeline pour de bon.

Un certain nombre l’acceptent directement : les tâches de chargement BigQuery et Snowflake pointées sur du JSON délimité par sauts de ligne, DuckDB lisant le fichier dans une clause FROM, ClickHouse avec son format JSONEachRow, et la plupart des routines d’import applicatives qui décrivent leur entrée comme un objet par ligne.

Un ensemble plus restreint attend un protocole plutôt que des enregistrements. Les requêtes en bloc Elasticsearch et OpenSearch intercalent une ligne d’instruction avant chaque document, si bien qu’un corps a deux fois plus de lignes que d’enregistrements et que cette sortie en est la matière brute plutôt que la charge utile elle-même. Le moyen de savoir de quoi il s’agit est de chercher les mots action ou metadata dans la description du format — s’ils apparaissent, on vous demande de produire les lignes supplémentaires.

Rien dans cette conversion n’est à sens unique. Convertir le résultat en JSON rassemble les lignes en un tableau, et parce que chaque ligne était déjà une valeur complète, le tableau que vous obtenez est le tableau dont vous êtes parti — mêmes enregistrements, même imbrication, même ordre des clés.

Cela mérite d’être su au moment de décider ce qu’on garde. Si le NDJSON est un artefact de transport pour un chargement, il n’y a aucune raison de l’archiver ; le JSON est la même information et d’autres outils le lisent plus volontiers. Si les enregistrements vont continuer à arriver, le NDJSON est la meilleure forme sur la durée, parce qu’y ajouter consiste à ajouter une ligne plutôt qu’à réécrire un crochet à la fin d’un gros fichier.

Tous les consommateurs n’en profitent pas. Si la destination est un programme qui va lire le fichier entier d’un coup — une fixture de test, un script de seed, un corps de requête, un import de configuration — un tableau JSON est ce qu’il attend, et le NDJSON n’ajoute qu’une étape de réassemblage à l’autre bout.

Et si les enregistrements vont être interrogés à répétition plutôt que chargés une fois, aucune des deux formes n’est idéale. Toutes deux répètent chaque clé sur chaque enregistrement, ce qui représente une part importante d’un vrai fichier. Un format en colonnes contient les mêmes lignes pour une fraction des octets et répond à une question sur deux champs en lisant deux champs, ce qu’un flux ne sait pas faire.

Dans l’onglet de votre navigateur, en JavaScript ordinaire, sans téléversement et sans compte. Le niveau gratuit accepte jusqu’à 100 Mo, et au-delà la contrainte est la mémoire plutôt qu’une politique quelconque de notre côté.

L’argument de confidentialité est concret pour toute personne qui prépare un chargement en masse. Les fichiers qu’on convertit pour l’ingestion sont des journaux d’événements, des historiques de commandes, des fiches d’utilisateurs et des pistes d’audit, et en remettre un à un service web pour qu’on lui retire ses crochets serait une drôle de transaction. Rien n’est envoyé ici, ce qui est facile à confirmer : ouvrez l’onglet réseau et convertissez un fichier.