Parquet naar JSON omzetten

Parquet is wat een dataplatform je meegeeft en JSON is wat al het andere opeet. Daar leeft deze omzetting: een fixture die naast de test in een repository moet staan, een seed voor een lokale mockdienst, een body om in een verzoek te plakken terwijl je uitzoekt waarom een endpoint het weigert, of vijftig rijen die je in een JSON-viewer wilt bekijken zonder DuckDB te installeren.

Let op dat de interessante gevallen allemaal klein zijn. Parquet bestaat om zeer grote tabellen goedkoop bevraagbaar te maken, en niets daarvan overleeft de oversteek — de kolomsgewijze indeling, de compressie, de statistieken waarmee een lezer hele rijgroepen kan overslaan. Wat je krijgt is een tekstdocument, en dat is het juiste artefact voor honderd rijen en het verkeerde voor tien miljoen.

Het Parquet-bestand wordt teruggezet naar rijen, en die rijen worden geschreven als een JSON-array op het hoogste niveau met inspringing van twee spaties en een afsluitende nieuwe regel. Kolomnamen worden objectsleutels precies zoals het schema ze spelt, ook als het geen geldige JavaScript-identifier zou zijn.

Er is geen envelop en geen metadatablok. Verwacht de bestemming de rijen onder een naam — `{"rows": […]}` is de gewone vorm — voeg die dan zelf toe; `jq '{rows: .}'` doet het in één stap. De lengte van de array is het aantal rijen, dus het is ook de snelste controle dat het extract bevat wat je is verteld.

Dit is de verrassing op deze pagina en het is de moeite waard om twee keer te lezen. Parquet heeft echte geneste types — LIST, STRUCT en MAP — en de lezer hier geeft ze terug als JavaScript-objecten, die vervolgens naar tekst worden geserialiseerd en als tekst in het veld geplaatst. Een kolom `tags` met twee waarden wordt in de uitvoer geen `["a","b"]`. Het wordt `"[\"a\",\"b\"]"`, aangehaald, met de interne aanhalingstekens ontsnapt.

Er gaat niets verloren en alles zit één stap uit bereik. `jq '.[0].tags[0]'` geeft een fout terug over een tekst zonder indices; `jq '.[0].tags | fromjson | .[0]'` geeft de waarde. Gaat de JSON een testfixture in, dan is het eerlijk om die kolommen eenmalig uit te pakken met `jq 'map(.tags |= fromjson)'` en de gestructureerde versie te committen, in plaats van een dubbele codering achter te laten die de volgende lezer van de fixture zelf moet ontdekken.

Een Parquet-tijdstempelkolom is een getypeerd geheel getal met een eenheid en een tijdzone-vlag vastgelegd in de footer. JSON heeft helemaal geen datumtype, dus elke waarde wordt geschreven als een ISO 8601-tekst — `2026-03-01T08:00:00.000Z` — wat ondubbelzinnig is, lexicografisch in de juiste volgorde sorteert, en wordt begrepen door `Date.parse`, `datetime.fromisoformat` en elke JSON-schemacontrole `format: date-time`.

Wat weg is, is de declaratie. Het bestand zegt niet meer dat de kolom een tijdstempel is; het zegt dat de kolom een tekst is die er toevallig zo uitziet. Alles verderop moet het opnieuw verteld worden — een `parse_dates`-argument, een schema, een cast. Voor een fixture is dat prima en expliciet. Voor een lading is het één plek extra om de tijdzone verkeerd te doen.

Parquet heeft een 64-bit geheeltalletype en JavaScript-getallen dragen 53 bits gehele-getalprecisie. In plaats van stilzwijgend af te ronden, wordt een waarde die niet past geschreven als een aangehaalde tekst; eentje die wel past wordt geschreven als een kaal getal.

De afweging is bewust en zit om de juiste kant: een ordernummer dat een teruggeeft dat net verschoven is, is een bug die niemand vindt tot het ertoe doet, terwijl een kolom die soms een getal is en soms een tekst tenminste zichtbaar is. Het betekent wel dat een kolom halverwege het bestand van type kan wisselen, wat een strikt JSON-schema niet zal waarderen. Is dat je bestemming, cast dan de hele kolom naar tekst in de query die het extract produceerde, en de JSON wordt consistent.

Een Parquet `BYTE_ARRAY` zonder UTF8-annotatie is bytes in plaats van tekst, en bytes hebben geen getrouwe representatie in JSON. Elke zo’n waarde wordt geschreven als een lowercase hex-tekst — twee tekens per byte, geen scheidingsteken, geen prefix.

Hex is omkeerbaar en duidelijk geen proza, wat de reden is om het te kiezen boven een poging tot decoderen. Het is ook twee keer zo groot als de bytes die het codeert en half zo groot als niets bruikbaars, dus is een binaire kolom groot en heb je hem niet nodig, laat hem dan vallen in de query in plaats van hem mee te slepen in de omzetting. Een hashkolom is prima; een ingebedde thumbnailkolom niet.

Een ontbrekende waarde in Parquet wordt `null` in de JSON, te onderscheiden van een lege tekst en van een nul. Dat klinkt onopvallend tot je het vergelijkt met de gescheiden doelen, waar zowel null als leeg samenvallen tot niets tussen twee scheidingstekens en geen enkele query erna nog verschil kan maken.

Voor een fixture is dat verschil het hele punt. Een test die controleert op de afwezigheid van een waarde heeft de afwezigheid nodig als representeerbaar, en JSON is het enige tekstdoel hier dat het representeert. Het is ook waarom een rondweg via JSON meer van een Parquet-bestand bewaart dan een rondweg via CSV, ook al draagt geen van beide het schema.

Aanzienlijk, en vanuit drie richtingen tegelijk. Parquet slaat elke kolom eenmaal op met zijn type gedeclareerd, dictionary-codeert dan herhaalde waarden en comprimeert de pagina’s; JSON herhaalt elke kolomnaam op elke rij, schrijft elk getal als decimale cijfers, en deze uitvoer laat elk veld op zijn eigen regel inspringen.

Reken op een orde van grootte in plaats van een percentage, en meer als de tabel breed is of de waarden zich sterk herhalen — een statuskolom van vijf verschillende teksten kost bijna niets in Parquet en zijn volle lengte op elke rij in JSON. Het hele document wordt ook in het geheugen als één tekenreeks opgebouwd voor het bewaard kan worden, wat het praktische plafond is, ruim voor de gratis grens van 100 MB. Neem een `LIMIT` op het extract in plaats van een warehousetabel om te zetten en te hopen.

De footer die het bestand zelfbeschrijvend maakte, komt niet mee. Kolomnamen overleven als sleutels en verder niets: niet de gedeclareerde types, niet de nullability, niet de compressie, niet de rijgroepstatistieken, niet de sleutel-waardemetadata die een producent er misschien in geschreven heeft.

Heb je DuckDB, dan drukt `DESCRIBE SELECT * FROM 'file.parquet'` het schema in één shellregel af en kost het tien seconden, en weten welke kolommen INT64 waren in plaats van DOUBLE verklaart het meeste wat vreemd oogt in de JSON. Heb je het niet, zet dan eerst een handvol rijen om en lees ze — de aangehaalde gehele getallen, de ISO-teksten en de ontsnapte geneste kolommen vertellen elk wat het brontype was.

In dit tabblad. Een in gewoon JavaScript geschreven Parquet-lezer wordt de eerste keer dat je een van deze paren gebruikt opgehaald en doet daarna lokaal zijn werk; het bestand zelf wordt nergens naartoe gestuurd, en het netwerktabblad tijdens een omzetting toont de lezer die binnenkomt en niets dat vertrekt.

Dat onderscheid doet er bij dit formaat meer toe dan bij de meeste, want Parquet is een warehouseartefact. Bestanden met deze extensie zijn extracts uit productietabellen — klanten, orders, events, salarissen — en ze komen binnen via een dataleam die anders een upload zou moeten melden. Hier valt er niets te melden.