Convertir JSON en Parquet

Un fichier Parquet porte un schéma dans son pied de page : chaque colonne a un nom et un seul type, et chaque ligne s’y conforme. C’est ce qui permet à un moteur de requête de vous dire la forme d’un fichier de deux gigaoctets sans en lire une seule ligne, et c’est la propriété pour laquelle le format existe.

Un tableau JSON n’offre pas une telle garantie. Les enregistrements sont des objets, chacun libre de porter les clés qu’il a, et rien dans le format n’empêche le quarantième enregistrement de contenir une chaîne dans un champ que les trente-neuf premiers ont tenu en nombre. La conversion doit fabriquer le schéma que le fichier n’a jamais eu, et chaque cas particulier de cette page vient de cette seule phrase.

Parquet n’a nulle part où mettre un objet dans une cellule, donc l’enregistrement est aplati avant d’être transposé : un objet client contenant une ville devient une colonne nommée customer.city, portant le type qu’elle avait dans le JSON. C’est le même aplatissement que pratiquent les écritures CSV, TSV, SQL et XLSX de ce site, et c’est délibéré — un même extrait imbriqué donne les mêmes noms de colonnes quel que soit celui des cinq vers lequel vous l’orientez.

Les tableaux sont le cas où il faut réfléchir, parce qu’ils s’aplatissent par position plutôt que par nom. Un tableau tags de a et b devient deux colonnes, tags.0 et tags.1, et la liste des colonnes est l’union sur l’ensemble du fichier — de sorte qu’un champ qui en compte habituellement deux et parfois quarante produit quarante colonnes, trente-huit d’entre elles nulles sur presque toutes les lignes. Quand une liste est vraiment de longueur variable, la joindre en une seule chaîne dans jq avant la conversion donne un schéma sur lequel on peut interroger.

Là où chaque enregistrement est un objet plat — un journal d’événements, un extrait de commandes, un tableau qu’une API a renvoyé page par page — la conversion fait exactement ce que vous voulez et le fait en une étape. Les clés deviennent des colonnes dans l’ordre de leur première apparition, les valeurs deviennent des données de colonne typées, et le résultat est un fichier que DuckDB interrogera sans aucune préparation.

Cela couvre une bonne part des vrais extraits JSON. Les événements d’analyse, les lignes de facturation, les soumissions de formulaires et la plupart des points d’accès de listes paginées sont plats par conception, parce que les systèmes qui les produisent écrivent des lignes. Un enregistrement qui imbrique quand même convertit — il arrive plus large, avec une colonne pointée par feuille — donc le coup d’œil au premier enregistrement sert à savoir à quoi ressemblera le schéma, et non à savoir si cela fonctionnera.

Les enregistrements qui ne sont pas d’accord sur les clés qu’ils portent sont réconciliés en prenant toutes les clés. Un champ présent dans le premier enregistrement et absent du suivant produit une colonne avec un null à la deuxième ligne, et un champ qui n’apparaît que dans les dix derniers enregistrements d’un million devient tout de même une colonne.

Cette réconciliation lit le tableau entier avant d’écrire quoi que ce soit, ce qui est le coût honnête du refus d’échantillonner. Le bénéfice est qu’un champ rare n’est jamais silencieusement abandonné, et la surprise qu’il produit est prévisible : convertir un échantillon de dix enregistrements donne moins de colonnes que convertir le fichier entier. Tirez le schéma d’une conversion de l’extrait complet, jamais de l’échantillon sur lequel vous avez testé.

JSON a de vrais types, ce qui est un avantage net sur une conversion depuis un tableur ou un CSV : un nombre arrive en nombre et un booléen en booléen, sans rien d’inféré d’après les caractères. Les booléens deviennent BOOLEAN, les nombres entiers dans la plage 32 bits deviennent INT32, tout autre nombre devient DOUBLE, et le texte reste texte.

Le cas où cela se télescope est celui où les enregistrements ne sont pas d’accord. Un champ qui est un nombre dans la plupart des enregistrements et une chaîne dans quelques-uns — un identifiant que certains systèmes entourent de guillemets et d’autres non, une quantité portant « n/a » — fait de la colonne entière une colonne texte, et les valeurs numériques y sont écrites en texte à côté des autres. C’est délibéré : prendre le type du premier enregistrement et passer les autres à null produirait un fichier qui se charge proprement et qui a silencieusement supprimé les valeurs qui ne collaient pas. Une colonne texte est visible et peut être convertie en une seule expression.

Parquet dispose d’un type entier 64 bits et cette conversion ne l’émet pas. Les valeurs passent par les nombres JavaScript, qui portent 53 bits de précision entière, si bien qu’une valeur au-delà de la plage 32 bits est écrite en DOUBLE au lieu de prétendre à une exactitude qu’elle n’a plus.

Pour les identifiants, cela compte, et la correction se fait en amont. Un export JSON qui écrit les références de commande en chaînes les conserve exactes à travers cette conversion et les fait arriver en colonne texte, ce qui est de toute façon ce que devrait être un identifiant. Un export qui les écrit en nombres nus a déjà perdu la précision au-delà de seize chiffres avant qu’aucun convertisseur n’ait vu le fichier.

Cinquante mille enregistrements de commandes générés, comportant six champs — un id, un code produit, une ville, une quantité, un prix et un drapeau — ont pesé 207 Ko en Parquet. Les mêmes enregistrements pesaient 4,8 Mo en JSON compact et 6,8 Mo en JSON joliment indenté, qui est la forme sous laquelle la plupart des exports arrivent réellement.

L’écart n’est pas dû à la compression seule. Chaque enregistrement JSON répète chaque clé, si bien que les noms de champ apparaissent cinquante mille fois chacun ; dans un stockage en colonnes ils n’apparaissent qu’une fois, dans le pied de page. Les valeurs répétées se compressent très bien quand elles sont côte à côte, ce qui explique que les colonnes ville et code produit ne coûtent presque rien ici. Attendez-vous à un gain important sur des données opérationnelles de ce genre et à un gain bien moindre sur des enregistrements qui sont surtout du texte libre distinct.

Un extrait JSON est souvent un objet avec une clé tenant le tableau — data, results, records. Cette enveloppe à clé unique est retirée pour vous et le tableau à l’intérieur est ce qui est converti, parce que c’est la forme que renvoie quasiment toute API paginée et que la retirer correspond à l’intention.

Deux clés est le point où cela s’arrête. Un fichier de la forme {"meta": {...}, "data": [...]} n’a pas de tableau évident à privilégier, donc l’objet entier devient une ligne et les enregistrements y sont aplatis par index : data.0.id, data.1.id, et ainsi de suite pour tous les enregistrements que le fichier contient. Le symptôme est sans ambiguïté une fois qu’on le connaît — un fichier Parquet à une ligne et plusieurs milliers de colonnes. Ramenez le fichier au tableau seul avec jq avant de convertir.

DuckDB lit le fichier directement dans une clause FROM, pandas en un seul appel, et Spark le traite comme une table native. Le fichier commence et finit par les quatre octets PAR1, ce qui est la signature reconnue par chacun d’eux.

La première chose à regarder est le schéma plutôt que les dix premières lignes. Deux questions répondent à presque tout : une colonne est-elle typée en chaîne là où vous attendiez un nombre, et le nombre de colonnes est-il celui que vous attendiez. La première vous dit quels enregistrements ne sont pas d’accord sur un type ; la seconde vous dit si un champ imbriqué ou un tableau de longueur variable a élargi le fichier au-delà de votre intention. Les deux sont bien moins chers à découvrir maintenant qu’après que le fichier a été joint à trois autres.

Dans le navigateur. L’écriture Parquet est du JavaScript ordinaire que cette page charge à la demande — pas de WebAssembly, pas de serveur — si bien qu’aucune requête ne transporte l’extrait ailleurs et qu’il n’y a ni compte, ni file d’attente, ni palier de plan. Le niveau gratuit accepte jusqu’à 100 Mo.

Le véritable plafond est la mémoire plutôt que ce chiffre, parce que le tableau entier est analysé, transposé en colonnes et écrit, de sorte que le jeu de données entier coexiste à un moment donné. Quelques dizaines de mégaoctets est un cas de routine et quelques centaines de mégaoctets est là où un onglet commence à peiner. Au-delà, un lecteur en flux dans un script est le bon instrument, et le dire vaut mieux qu’échouer au milieu d’un gros fichier. Le registre note aussi le support de Parquet comme inégal pour une raison précise : il est binaire, il n’est pas éditable, et une collègue sans le bon outillage ne peut tout simplement pas l’ouvrir — si le fichier va à une personne plutôt qu’à un moteur, envoyez un tableur.