Parquet naar NDJSON omzetten

Een Parquet-bestand legt het type van elke kolom vast in zijn voettekst. Zet het om naar CSV of naar tabgescheiden tekst en die vastlegging is weg: elke waarde wordt tekens, en wat het bestand daarna leest, leidt types opnieuw af uit hoe die tekens eruitzien — meestal anders, en altijd zonder het voordeel van het schema dat er al was.

JSON heeft eigen types. Een getal blijft een getal, een boolean blijft een boolean en een null blijft null, dus het record dat aan de andere kant aankomt, zegt hetzelfde over zichzelf als de Parquet-kolom deed. Dat is geen klein verschil als de bestemming een dienst of wachtrij met een schema is, want het haalt een hele categorie "de API weigerde het veld omdat het een string was" uit de pijplijn.

Dit is de beperking die je moet kennen voordat je iets op de uitvoer bouwt. Parquet houdt native lijsten, structs en maps, en die kolommen worden in de JSON geschreven als strings met JSON erin, niet als geneste JSON. Een lijstkolom komt aan als "[\"a\",\"b\"]", wat een correcte en volledige weergave van de waarde is en niet de vorm die een consument die een array verwacht, accepteert.

Het is één stap om te herstellen. jq -c '.tags |= fromjson' over het omgezette bestand maakt van dat veld een echte array, en hetzelfde geldt voor een struct-kolom. Het expliciet doen is ook het moment om te beslissen hoe het veld eigenlijk moet heten en of de bestemming het genest wil — veel bestemmingen accepteren de string prima.

JSON heeft geen datumtype. Een tijdstempelkolom wordt daarom geschreven als een ISO 8601-string — 2024-03-11T09:30:00.000Z — die elke taal, database en schemavalidator zonder aanwijzing over het formaat parst, en die chronologisch sorteert als gewone tekst.

Het alternatief zou een epochgetal zijn, en dat is erger in een record dat een mens mogelijk moet lezen: een veld met 1710149400000 is onbegrijpelijk zonder de epoch en de eenheid te kennen, en de twee gangbare eenheden verschillen met een factor duizend. Verlangt de bestemming per se epoch-milliseconden, dan is omrekenen vanuit ISO één expressie.

Parquet heeft een 64-bits geheeltalig type, en JSON-getallen zijn in de praktijk beperkt tot wat de parsers aan beide kanten exact kunnen weergeven — voor de meeste daarvan 53 bits. Een waarde daarboven kan niet als getal worden gedragen zonder haar te veranderen.

De omzetting schrijft die als string. Een waarde binnen het veilige bereik blijft een getal, een daarbuiten wordt een aangehaalde string met elk cijfer intact, en een kolom die de grens overspant, bevat allebei. Dat gemengde type is licht vervelend en het is de juiste ruil: een bestelreferentie die is afgerond, ziet er nog steeds uit als een bestelreferentie, komt nergens mee overeen, en is heel lastig te traceren.

Het bestand is één compleet JSON-object per regel en verder niets — geen openhaakje, geen komma’s tussen records, geen sluithaakje. Een parser die een JSON-array verwacht, faalt op de tweede regel, en dat is het formaat dat werkt zoals bedoeld, geen fout.

Wat het ontbreken oplevert, is dat een consument een regel kan lezen, erop reageren, hem weggooien en verder gaan, ongeacht de omvang van het bestand. Het betekent ook dat de uitvoer adresseerbaar is per regel: head -n 1000 geeft een steekproef die zelf geldige invoer is voor al het andere, split -l levert laadbare stukken op.

Dit is de gangbare vorm van de klus. Een tabel staat in een dataplatform, en iets erbuiten — een zoekindex, een berichtenwachtrij, een dienst die gevuld moet worden, een testomgeving die realistische data nodig heeft — neemt JSON en heeft nog nooit van Parquet gehoord. NDJSON is het formaat dat ertussen zit en heeft niets meer nodig dan een regeleinde.

Een shell-lus die regels leest en elk stuurt, is genoeg voor een kleine terugvulling, en voor een grotere voedt hetzelfde bestand een bulk-endpoint of een producer-script zonder aanpassing. Het enige om eerst te controleren, zijn de veldnamen: een dataplatform geeft kolommen namen die door de pijplijn zijn bepaald, en een dienst wil meestal iets anders.

Een null in een Parquet-kolom wordt in de JSON geschreven als null, wat een onderscheid bewaart dat geen gescheiden formaat kan dragen: null en de lege string zijn verschillende waarden, en ze komen ook verschillend aan.

Dat doet ertoe waar de bestemming een schema heeft. Een veld gedeclareerd als string weigert null tenzij het nullable is verklaard, en een validator vertelt je dat bij het record waar het gebeurde in plaats van pas bij het laden. Beide zijn betere mislukkingen dan het gescheiden alternatief, waar een null en een lege string dezelfde nul tekens zijn.

De uitvoer is veel groter dan het bestand waar het uit kwam. Elk record herhaalt elke veldnaam, elke string wordt aangehaald, en niets van de compressie, woordenboekcodering of binaire weergave die het Parquet-bestand klein hield, overleeft in tekst.

Dat is te accepteren omdat dit bestand een transportartefact is. Het bestaat om eenmaal door een consument gelezen te worden en daarna verwijderd, en de blijvende kopie blijft Parquet. Wordt de NDJSON bewaard in plaats van geconsumeerd, dan is dat een teken dat er iets misging in het ontwerp.

De Parquet-lezer is een bibliotheek die deze pagina op aanvraag laadt, en de JSON wordt daar geschreven, dus geen verzoek draagt het bestand. Voor een extract uit het midden van een platform — vóór de aggregatie, vóór de maskering — is dat meestal de beperking die bepaalt of een online converter überhaupt gebruikt mag worden.

Elke rij wordt volledig opgebouwd voordat er iets wordt geschreven, dus geheugen is het plafond. Parquet is gecomprimeerd, dus een bescheiden bestand kan flink uitdijen en de grens komt eerder dan de schijfgrootte suggereert. Voor een grote tabel leest DuckDB het Parquet-bestand en schrijft het in één statement newline-delimited JSON zonder een van beide vast te houden.

Kan de consument Parquet lezen, laat het dan. Elk warehouse, elke query-engine en de meeste moderne datalibrary’s doen dat, en het origineel doorgeven bewaart het schema, houdt de overdracht klein en verwijdert een stap waar de types kunnen verschuiven.

Zet om als de consument echt alleen JSON spreekt, wat de meeste diensten, wachtrijen en zoekindexen zijn. Dat is een reëel en blijvend verschil — operationele systemen wisselen records uit, analytische systemen wisselen kolommen uit — en deze omzetting is de brug daartussen, geen vervanging van beide.