Convertir Parquet en NDJSON

Un fichier Parquet déclare le type de chaque colonne dans son pied de page. Convertissez-le en CSV ou en texte tabulé et cette déclaration disparaît : chaque valeur devient des caractères, et ce qui lit ensuite le fichier infère à nouveau les types à partir de l’apparence des caractères — généralement autrement, et toujours sans bénéficier du schéma qui se trouvait à côté.

JSON a ses propres types. Un nombre reste un nombre, un booléen reste un booléen, un null reste null, donc l’enregistrement qui arrive à l’autre bout dit de lui-même la même chose que ce que disait la colonne Parquet. Ce n’est pas une petite différence quand la destination est un service ou une file avec un schéma, parce que cela supprime toute la classe « l’API a rejeté l’enregistrement parce que le champ était une chaîne » au milieu du pipeline.

C’est la limitation à connaître avant de construire quoi que ce soit sur la sortie. Parquet porte nativement des listes, des structures et des maps, et ces colonnes sont écrites dans le JSON comme des chaînes contenant du JSON plutôt que comme du JSON imbriqué. Une colonne de liste arrive sous la forme `"[\"a\",\"b\"]"`, qui est un enregistrement correct et complet de la valeur, et qui n’est pas la forme qu’attendra un consommateur qui s’attend à un tableau.

Il suffit d’une passe pour réparer. `jq -c '.tags |= fromjson'` sur le fichier converti transforme ce champ en vrai tableau, et il en va de même pour une colonne de structure. Le faire explicitement est aussi l’occasion de décider comment ce champ doit vraiment s’appeler et si la destination veut l’imbrication ou pas — beaucoup accepteront la chaîne sans broncher. Ce qui compte, c’est de le savoir, parce qu’un champ qui ressemble à une structure dans une revue de code et qui est une chaîne à l’exécution est une mauvaise surprise dans un test d’intégration.

JSON n’a pas de type date. Une colonne d’horodatage est donc écrite comme une chaîne ISO 8601 — `2024-03-11T09:30:00.000Z` — que chaque langage, chaque base de données et chaque validateur de schéma parse sans qu’on lui dise un format, et qui se trie chronologiquement en texte brut.

L’alternative serait un nombre epoch, et elle est pire sur un enregistrement qu’une personne peut avoir à lire : un champ valant 1710149400000 est illisible sans connaître à la fois l’epoch et l’unité, et les deux unités courantes diffèrent d’un facteur mille. Si la destination insiste sur des millisecondes epoch, convertir depuis l’ISO est une expression et la direction est sans ambiguïté ; aller dans l’autre sens depuis un nombre nu exige une hypothèse qu’il faudrait documenter.

Parquet a un type entier 64 bits et les nombres JSON sont, en pratique, limités par ce que les parseurs de chaque côté peuvent représenter exactement — ce qui, pour la plupart, est 53 bits. Une valeur au-delà ne peut pas être portée en nombre sans la modifier.

La conversion les écrit en chaînes. Une valeur dans la plage sûre reste un nombre, une valeur hors de cette plage devient une chaîne entre guillemets avec chaque chiffre intact, et une colonne qui chevauche la limite contiendra les deux. Ce type mêlé est légèrement gênant et c’est le bon compromis : une référence de commande arrondie ressemble exactement à une référence de commande, ne correspond à rien, et est très difficile à tracer. Si la destination a un schéma, déclarez ce champ comme chaîne et convertissez-le à l’arrivée.

Le fichier est un objet JSON complet par ligne et rien d’autre — pas de crochet ouvrant, pas de virgules entre enregistrements, pas de crochet fermant. Un parseur qui attend un tableau JSON échouera à la deuxième ligne, et c’est le format qui fonctionne comme prévu plutôt qu’un défaut.

Ce que cette absence permet, c’est qu’un consommateur puisse lire une ligne, la traiter, la jeter, et passer à la suivante, quelle que soit la taille du fichier. Cela veut dire aussi que la sortie est adressable par ligne : `head -n 1000` donne un échantillon qui est lui-même un fichier d’entrée valide pour tout le reste, `split -l` produit des morceaux chargeables, et une relecture échouée peut reprendre depuis un numéro de ligne plutôt que depuis le début.

C’est la forme courante de la tâche. Une table vit dans une plateforme de données, et quelque chose à l’extérieur — un index de recherche, une file de messages, un service en cours de backfill, un environnement de pré-production qui a besoin de données réalistes — prend du JSON et n’a jamais entendu parler de Parquet. NDJSON est le format qui s’intercale, et il n’a besoin que d’un retour à la ligne comme cadrage.

Une boucle shell lisant des lignes et postant chacune suffit pour un petit backfill, et pour un plus grand le même fichier alimente un endpoint en bloc ou un script producteur sans modification. La seule chose à vérifier d’abord est le nom des champs : une plateforme de données donne aux colonnes des noms marqués par le pipeline qui les a produites, et un service veut en général autre chose. Renommer avec jq avant l’envoi est une seule expression et se relit plus facilement qu’un mapping enfoui dans le consommateur.

Un null dans une colonne Parquet est écrit `null` dans le JSON, ce qui préserve une distinction qu’aucun format délimité ne peut porter : null et chaîne vide sont des valeurs différentes, et elles arrivent différentes.

Cela compte quand la destination a un schéma. Un champ déclaré comme chaîne rejettera null à moins qu’il ne soit déclaré nullable, et un validateur vous le dira sur l’enregistrement concerné plutôt qu’au moment du chargement. Ce sont dans les deux cas de meilleurs échecs que l’alternative délimitée, où un null et une chaîne vide sont les mêmes zéro caractères et où la différence est déjà perdue au moment où quelque chose la vérifie.

La sortie est bien plus grande que le fichier dont elle vient. Chaque enregistrement répète chaque nom de champ, chaque chaîne est entre guillemets, et rien de la compression, de l’encodage par dictionnaire ou de la représentation binaire qui rendaient le Parquet petit ne survit au passage en texte.

Cela est acceptable parce que ce fichier est un artefact de transport. Il existe pour être lu une fois par un consommateur puis supprimé, et la copie durable reste en Parquet. Là où le NDJSON est conservé au lieu d’être consommé, c’est le signe que quelque chose a dérapé dans la conception — un fichier columnaire compressé est meilleur à chaque étape du stockage de données qu’un fichier texte avec les noms de champs répétés sur chaque ligne.

Le lecteur Parquet est une bibliothèque chargée à la demande par cette page et le JSON y est écrit, donc aucune requête ne transporte le fichier. Pour un extrait pris au milieu d’une plateforme — avant agrégation, avant masquage — c’est généralement la contrainte qui décide si un convertisseur en ligne peut être utilisé.

Chaque ligne est matérialisée avant que quoi que ce soit ne soit écrit, donc la mémoire est le plafond. Parquet est compressé, et un fichier modeste peut beaucoup gonfler, et la limite arrive plus vite que la taille sur disque ne le suggère. Pour une grande table, DuckDB lira le Parquet et écrira le NDJSON en une instruction sans rien garder en mémoire, et il permet de ne sélectionner que les colonnes que la destination veut réellement.

Si le consommateur sait lire du Parquet, laissez-le faire. Chaque entrepôt, chaque moteur de requête et la plupart des bibliothèques de données modernes le font, et passer l’original préserve le schéma, garde le transfert petit, et supprime une étape où les types peuvent dériver.

Convertissez quand le consommateur ne parle vraiment que JSON, et rien d’autre, ce qui est la plupart des services, la plupart des files et la plupart des index de recherche. C’est une séparation réelle et permanente — les systèmes opérationnels échangent des enregistrements, les systèmes analytiques échangent des colonnes — et cette conversion est le pont entre les deux plutôt qu’un substitut à l’un ou l’autre.