Convertir CSV en NDJSON

Un CSV nomme ses colonnes une fois, en haut, et chaque ligne ensuite est positionnelle — le troisième champ est la ville parce que le troisième en-tête l’a dit. Le NDJSON fait l’inverse : chaque ligne est un objet complet portant ses propres clés, donc la soixante-dix-millième fiche est aussi lisible isolément que la première.

C’est le compromis que fait la conversion, et il n’est pas gratuit. Répéter les noms de clés à chaque ligne grossit le fichier, parfois considérablement sur une table de valeurs courtes avec des en-têtes longs. Ce que vous y gagnez, c’est qu’aucune ligne ne dépend d’une autre, et c’est ce qui rend possibles toutes les autres propriétés de cette page.

La raison pour laquelle cette conversion est généralement demandée, ce n’est pas l’élégance. C’est que vous avez onze exports mensuels, le système a ajouté un champ en avril, et il n’y a aucun moyen de concaténer un fichier à quatorze colonnes avec un fichier à quinze. Joindre les CSV laisse une ligne d’en-tête au milieu des données, et même après l’avoir retirée, les champs ne sont plus alignés.

Le NDJSON n’a pas ce problème. Des enregistrements avec des jeux de clés différents coexistent dans le même fichier tout à fait légitimement, et tout consommateur raisonnable — un moteur de requête, un job de chargement, un script — traite une clé manquante comme absente plutôt que comme une fiche cassée. Convertissez chaque export séparément, concaténez les résultats avec `cat`, et la différence de schéma devient un fait sur des fiches individuelles au lieu d’une défaillance structurelle.

Parce qu’un enregistrement se termine là où la ligne se termine, le fichier peut être coupé partout où il y a un saut de ligne et les deux moitiés restent valides. `split -l 100000` produit des chunks chargeables. `head -n 1000` produit un échantillon que vous pouvez réellement passer contre un schéma. Un chargement échoué peut être repris à partir d’un numéro de ligne plutôt que recommencé.

Ajouter fonctionne pour la même raison : de nouveaux enregistrements vont à la fin avec `>>` et rien au-dessus n’a besoin d’être réécrit. Faire l’équivalent sur un CSV demande de vérifier si l’en-tête est présent, si l’ordre des colonnes correspond, et si la dernière ligne se terminait par un saut de ligne, et se tromper sur l’un de ces points corrompt le fichier silencieusement plutôt que bruyamment.

JSON distingue le nombre 7 de la chaîne « 7 » et un CSV ne le fait pas, donc quelque chose doit décider, et ce qui décide c’est l’inférence sur le texte. Les valeurs qui se parsent comme des nombres deviennent des nombres JSON — `1e5` arrive en sortie comme 100000 — tandis que `true` et `false` deviennent des booléens et que tout le reste reste une chaîne.

La supposition est correcte pour les quantités, les prix et les indicateurs, et fausse pour les identifiants. `007` devient `7`, et une fois que c’est un nombre dans le JSON, il n’y a plus rien pour le récupérer. Si l’export contient des codes plutôt que des mesures, la parade la moins coûteuse est de les rendre non ambigus dans la source : un préfixe, ou une colonne déjà exportée en texte, les deux survivent. Le test général est de savoir si additionner deux valeurs de la colonne aurait un sens ; si non, c’est un identifiant et il voulait rester une chaîne.

Une cellule vide est écrite `null` plutôt que comme une chaîne vide. C’est une décision réelle et qui mérite d’être connue, parce que les deux ne sont pas la même chose pour tout ce qui consomme le fichier : un schéma JSON avec `"type": "string"` rejette null, et un chargement en base mettra un null là où vous attendiez peut-être la chaîne vide que vous voyiez dans la source.

Ce que la conversion ne peut pas faire, c’est vous dire laquelle des deux l’export voulait dire. Un CSV a exactement une façon d’écrire « rien ici » et elle est utilisée à la fois pour « ce champ est vide » et « ce champ ne s’applique pas ». Si la distinction compte en aval, elle doit être encodée explicitement dans la source — une valeur sentinelle, ou une seconde colonne — avant qu’une conversion la voie.

Le fichier est conçu pour `jq -c`, qui le lit une valeur à la fois sans tenir l’ensemble en mémoire. `jq -r ".city"` sur un export converti imprime une ville par ligne ; `jq -s "length"` compte les enregistrements ; un filtre `select` produit un fichier NDJSON plus petit qui reste lui-même un fichier NDJSON valide.

La même chose s’applique à tout ce qui lit des lignes. `grep` sur le fichier brut fonctionne et est honnête, parce qu’un enregistrement ne peut pas s’étendre sur deux lignes et ne peut pas être coupé en deux par une correspondance. `wc -l` donne le compte exact d’enregistrements, ce qui est un détail jusqu’à ce que vous le compariez au fait de compter des lignes d’un CSV où une adresse entre guillemets contient un saut de ligne.

Attendez-vous à grossir. Chaque ligne répète les noms de clés, chaque chaîne est entre guillemets, et la ponctuation d’un objet est ajoutée autour des valeurs. Sur une table de codes courts avec des en-têtes descriptifs, le fichier peut doubler ; sur une table de longs champs de texte libre, la différence est faible, parce que les valeurs dominent.

La compression referme l’essentiel de l’écart, puisque les clés répétées sont exactement ce qu’un compresseur traite le mieux, et un NDJSON gzippé est en général proche d’un CSV gzippé des mêmes données. Si la taille au repos est ce qui compte vraiment, plutôt que la forme diffusable, c’est un signal pour regarder Parquet, où les noms de colonnes sont stockés une fois dans un pied de page plutôt qu’à chaque enregistrement.

Le NDJSON est une forme de conteneur, pas un contrat. Une destination qui ingère des lignes JSON aura quand même des opinions sur les noms de champs, sur les formats de date, et sur la question de savoir si un null est permis à une position donnée, et aucune de ces opinions n’est tranchée par cette conversion.

Les deux qui piègent les gens sont les dates et les identifiants. Une date dans un CSV est du texte et reste du texte, donc la chaîne qu’a choisie le système exportateur est ce qui arrive — et si cette chaîne est `03/04/2024`, l’ambiguïté voyage avec. Les identifiants, comme ci-dessus, peuvent être devenus des nombres. Les deux se règlent à peu de frais par un `jq` d’une ligne sur le fichier converti, et beaucoup plus cher après le chargement.

Lire le CSV et écrire les lignes JSON sont du JavaScript ordinaire, chargé par cette page à la demande. Aucune requête ne transporte le fichier, donc un export client nocturne ou un extrait financier peut être converti sans devenir la copie de quelqu’un d’autre.

L’offre gratuite s’arrête à 100 Mo par fichier, et en deçà le plafond est la mémoire. La table entière est construite avant que quoi que ce soit soit écrit, ce qui met des dizaines de mégaoctets confortément à portée et les derniers pas vers 100 Mo au point où un onglet de navigateur commence à peiner. Pour un export plus gros, un lecteur CSV en flux dans un script est le bon outil — et la destination étant un flux, écrire ce script est souvent l’état final correct.

Choisissez un tableau JSON brut à la place quand l’ensemble va être chargé en une fois par quelque chose qui attend un tableau — une charge utile d’API, une fixture de test, un fichier de configuration. Le NDJSON y est pire qu’inutile, parce que la plupart des parseurs JSON le rejetteront dès la deuxième ligne.

Gardez le CSV si la destination est un tableur ou un écran d’import qui le nomme, parce que ni l’un ni l’autre ne gagne quoi que ce soit à avoir des enregistrements sur des lignes. Et choisissez Parquet quand les mêmes données seront interrogées de manière répétée plutôt qu’ingérées une fois : il stocke les noms de colonnes une fois, garde les types explicitement au lieu de les inférer, et tient en une fraction de la place sur disque.