Convertir Parquet en JSON

CSV et TSV aplatissent. Tout devient un objet à deux dimensions : un nom de colonne, une valeur par cellule. Une structure qui était hiérarchique dans la source perd ses niveaux à la sortie, et l’information sur la forme de la donnée s’évapore en route.

JSON, lui, porte des objets imbriqués, des tableaux de longueur variable, et des valeurs nulles distinctes des chaînes vides. La sortie d’une conversion Parquet en JSON est un arbre qui ressemble à la structure que la source décrivait, et c’est ce qui rend le format utile : un service en aval, un validateur de schéma, un inspecteur de payload, voit la même organisation que la plateforme de données d’origine.

Le lecteur Parquet normalise tout à l’entrée : les entiers 64 bits deviennent des nombres JavaScript ou, s’ils dépassent 2^53, des chaînes ; les dates deviennent des chaînes ISO 8601 ; les valeurs binaires deviennent du texte hexadécimal en minuscules. Le résultat de cette lecture est ce qui est écrit en JSON, et il faut le savoir pour ne pas chercher une fidélité que le module ne prétend pas avoir.

Pour la plupart des tables, la conversion est exacte. Un BOOLEAN devient un booléen, un DOUBLE devient un nombre, un INT32 dans la plage sûre devient un nombre. C’est aux limites que la transformation se voit : un identifiant de commande 64 bits hors plage devient une chaîne, et la colonne n’est plus homogène.

Les nombres JSON sont, en pratique, limités à 53 bits de précision par les parseurs des deux côtés. Un identifiant Snowflake ou Stripe, un timestamp nanoseconde, un compteur au-delà de 9 quadrillions, ne peut pas être porté en nombre sans perdre des chiffres.

La conversion l’écrit en chaîne. Une valeur dans la plage sûre reste un nombre, une valeur hors plage devient une chaîne entre guillemets, et une colonne qui chevauche la limite contient les deux. C’est légèrement gênant et c’est le bon compromis : un identifiant tronqué ressemble exactement à un identifiant légitime, ne correspond à rien en aval, et est presque impossible à tracer. Déclarez ces champs comme chaînes dans le schéma de la destination et convertissez à l’arrivée plutôt que de laisser un parseur JSON prendre une décision silencieuse.

JSON n’a pas de type date. Une colonne timestamp Parquet arrive donc comme `2024-03-11T09:30:00.000Z`, et c’est lisible par chaque langage, chaque base de données, chaque validateur de schéma, sans qu’on lui dise un format. L’ordre lexicographique correspond à l’ordre chronologique, ce qui simplifie un tri ou un merge.

L’alternative, un nombre epoch, est moins lisible et piège par l’unité : un 1710149400000 peut être des millisecondes ou des microsecondes, et les deux unités courantes diffèrent d’un facteur mille. Si la destination insiste sur des millisecondes epoch, la conversion depuis l’ISO est une seule expression, sans ambiguïté sur la direction ; l’inverse, depuis un nombre nu, exige une hypothèse qu’il faudrait documenter.

La sortie est considérablement plus grosse que le Parquet dont elle vient. Chaque enregistrement répète chaque nom de champ, chaque chaîne est entre guillemets et échappée au besoin, et rien de la compression, de l’encodage par dictionnaire, ou de la représentation binaire en colonne ne survit au passage en texte.

Ce n’est pas un format de stockage, c’est un format de transport. Le fichier existe pour être lu une fois par un consommateur puis supprimé, et la copie durable reste en Parquet. Quand un NDJSON ou un JSON commence à s’accumuler dans un bucket, c’est le signe que quelque chose a dérapé : un fichier columnaire compressé est meilleur à chaque étape du stockage de données qu’un fichier texte avec les noms de champ répétés sur chaque ligne.

Un null dans une colonne Parquet est écrit `null` dans le JSON. C’est 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.

Pour une destination qui valide un schéma, c’est l’information correcte. Un champ déclaré chaîne rejettera null à moins qu’il ne soit déclaré nullable, et un validateur vous le dira sur l’enregistrement concerné au moment de l’ingestion, pas au moment où quelqu’un remarque une statistique bizarre trois mois plus tard. Ce sont dans les deux cas de meilleurs échecs que l’alternative délimitée, où null et chaîne vide sont indiscernables et où la différence est déjà perdue au moment où quelque chose la vérifie.

Cette conversion écrit un objet JSON complet par ligne, sans crochet ouvrant, sans virgules entre enregistrements, sans crochet fermant. C’est le format JSON Lines, aussi appelé NDJSON, et c’est ce qui rend la sortie adressable par ligne : `head -n 1000` donne un échantillon qui est lui-même un fichier d’entrée valide pour tout le reste.

L’autre forme, un tableau unique `[ {...}, {...} ]`, est lisible par plus de logiciels mais perd cette propriété. Si la destination sait gérer JSON Lines, c’est presque toujours le bon choix : un parseur peut commencer à émettre avant la fin, un fichier interrompu est réutilisable jusqu’à la dernière ligne complète, et un rejouage peut reprendre depuis un offset plutôt que depuis le début.

Parquet porte des structures et des listes, et ces colonnes sont lues par le module comme des objets JavaScript ou des tableaux JavaScript. Dans la sortie JSON, elles restent sous cette forme : un champ de structure arrive comme un objet imbriqué, un champ de liste arrive comme un tableau.

C’est différent de ce qui se passe en CSV ou en TSV, où la même colonne est aplatie en un chemin pointé comme `address.city` ou transformée en chaîne `[object Object]`. La conversion en JSON garde la forme, et c’est précisément pour cela qu’une équipe prend cette voie plutôt que de passer par une étape de dénormalisation intermédiaire.

C’est l’usage caractéristique de la paire. 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. JSON Lines 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 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 avant l’envoi est une seule expression et se relit plus facilement qu’un mapping enfoui dans le consommateur.

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 en mémoire 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 JSON 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.