Parquet in JSON umwandeln

Eine lokale Testumgebung oder ein Mock-Server erwartet gewöhnlich eine einzelne JSON-Datei, die sich einlesen lässt, ohne DuckDB, pandas oder eine Warehouse-Verbindung aufzusetzen — genau dort setzt diese Umwandlung an. Ein Entwicklerteam bekommt einen Parquet-Auszug aus dem Data Warehouse, muss daraus aber eine Fixture bauen, die neben dem Test im Repository liegt, oder eine Handvoll Zeilen in einer Anfrage verschicken.

Enthält dieser Auszug personenbezogene Daten, etwa Kundendatensätze für einen Integrationstest, lohnt sich ohnehin ein zweiter Blick, bevor er irgendwo landet — auch als anonymisierte Testfixture. Wo diese Prüfung schon erledigt ist, bleibt die eigentliche technische Frage: Wie kommt eine typisierte Spaltendatei zu einem lesbaren JSON-Dokument.

Die Parquet-Datei wird zurück in Zeilen umgewandelt, und diese Zeilen werden als ein einziges JSON-Array mit zwei Leerzeichen Einrückung und abschließendem Zeilenumbruch geschrieben. Spaltennamen werden zu Objektschlüsseln, genau so, wie das Schema sie benennt, auch wenn ein Name kein gültiger JavaScript-Bezeichner wäre.

Es gibt keine Hüllstruktur und keinen Metadatenblock. Wird am Ziel ein benannter Schlüssel erwartet — `{"rows": […]}` ist die übliche Form —, lässt sich das nachträglich mit einer Zeile `jq '{rows: .}'` ergänzen. Die Länge des Arrays ist zugleich die Zeilenzahl und damit die schnellste Prüfung, ob der Auszug tatsächlich das enthält, was zugesagt wurde.

Das ist die Überraschung auf dieser Seite und lohnt sich, zweimal zu lesen. Parquet kennt echte verschachtelte Typen — LIST, STRUCT und MAP —, und der hier verwendete Leser gibt sie als JavaScript-Objekte zurück, die anschließend zu Text serialisiert und als Zeichenkette in das Feld geschrieben werden. Eine `tags`-Spalte mit zwei Werten wird in der Ausgabe nicht zu `["a","b"]`. Sie wird zu `"[\"a\",\"b\"]"`, in Anführungszeichen, mit maskierten inneren Anführungszeichen.

Nichts geht dabei verloren, alles liegt nur einen Schritt entfernt. `jq '.[0].tags[0]'` meldet einen Fehler, weil eine Zeichenkette keine Indizes kennt; `jq '.[0].tags | fromjson | .[0]'` liefert den Wert. Wird die JSON-Datei zu einer Test-Fixture, lohnt sich, solche Spalten einmalig mit `jq 'map(.tags |= fromjson)'` aufzulösen und die strukturierte Fassung zu committen, statt eine doppelte Kodierung im Repository zu hinterlassen, die die nächste Person erst entdecken muss.

Eine Zeitstempel-Spalte in Parquet ist eine typisierte Ganzzahl mit Einheit und Zeitzonenkennzeichnung im Dateifuß. JSON kennt gar keinen Datumstyp, jeder Wert wird deshalb als ISO-8601-Zeichenkette geschrieben — `2026-03-01T08:00:00.000Z` —, eindeutig, in Textform korrekt sortierbar und von `Date.parse`, `datetime.fromisoformat` und jeder JSON-Schema-Prüfung mit `format: date-time` verstanden.

Verloren geht die Deklaration selbst: Die Datei sagt nicht mehr, dass die Spalte ein Zeitstempel ist, sondern nur noch, dass sie eine Zeichenkette ist, die wie einer aussieht. Das lesende System muss es erneut erfahren — über ein Schema, eine explizite Umwandlung. Für eine Fixture ist das unproblematisch und offensichtlich; bei einem Import ist es eine zusätzliche Stelle, an der die Zeitzone falsch geraten werden kann.

Parquet kennt 64-Bit-Ganzzahlen, JavaScript-Zahlen stellen Ganzzahlen nur bis 53 Bit exakt dar. Statt einen Wert außerhalb dieses Bereichs stillschweigend zu runden, wird er als Zeichenkette in Anführungszeichen geschrieben; ein Wert innerhalb des Bereichs bleibt eine gewöhnliche Zahl.

Das ist eine bewusste und richtige Entscheidung — eine Bestellnummer, die um eins verschoben zurückkommt, ist ein Fehler, der niemandem auffällt, bis er wehtut, während eine Spalte, die mal Zahl und mal Zeichenkette ist, wenigstens sichtbar ist. Für eine strikte JSON-Schema-Prüfung ist das trotzdem lästig, weil sich der Typ innerhalb der Spalte ändern kann. Wo das stört, hilft, die ganze Spalte schon in der Abfrage, die den Auszug erzeugt, auf Text zu casten.

Ein Parquet-`BYTE_ARRAY` ohne UTF8-Kennzeichnung ist Binärdaten, keine Zeichenkette, und Binärdaten haben in JSON keine natürliche Darstellung. Jeder solche Wert wird als kleingeschriebener Hexadezimalwert geschrieben — zwei Zeichen je Byte, ohne Trennzeichen, ohne Präfix.

Hexadezimal ist rückführbar und eindeutig kein Fließtext, deshalb die Wahl statt eines Dekodierungsversuchs. Es ist auch doppelt so groß wie die kodierten Bytes selbst — bei einer großen und nicht benötigten Binärspalte lohnt sich, sie schon in der Abfrage wegzulassen. Ein Hashwert ist unproblematisch, eine eingebettete Miniaturansicht ist es nicht.

Ein fehlender Wert in Parquet wird in der JSON-Ausgabe zu `null`, unterscheidbar von einer leeren Zeichenkette und von einer Null als Zahl. Das klingt unspektakulär, bis man es mit den textbasierten Zielen vergleicht, bei denen sowohl ein fehlender als auch ein leerer Wert zu nichts zwischen zwei Trennzeichen zusammenfallen und keine spätere Abfrage die beiden noch unterscheiden kann.

Für eine Test-Fixture ist genau das entscheidend: Ein Test, der die Abwesenheit eines Werts prüft, braucht diese Abwesenheit auch in den Testdaten darstellbar — und JSON ist unter den hier angebotenen Textformaten das einzige, das das leistet.

Deutlich größer, aus mehreren Richtungen gleichzeitig. Parquet speichert jede Spalte einmal mit deklariertem Typ, kodiert wiederkehrende Werte per Wörterbuch und komprimiert die Seiten; JSON wiederholt jeden Spaltennamen in jeder Zeile, schreibt jede Zahl als Dezimalziffern aus, und diese Ausgabe rückt zusätzlich jedes Feld in eine eigene Zeile ein.

Eine Größenordnung ist realistischer als ein Prozentsatz, mehr noch bei breiten Tabellen oder stark wiederkehrenden Werten — eine Statusspalte mit fünf möglichen Zeichenketten kostet in Parquet fast nichts und in jeder JSON-Zeile ihre volle Länge. Das gesamte Dokument entsteht außerdem als eine einzige Zeichenkette im Arbeitsspeicher, bevor irgendetwas gespeichert wird — die praktische Grenze liegt deshalb deutlich vor der freien 100-MB-Obergrenze. Ein `LIMIT` auf den Auszug ist der bessere erste Schritt als das Umwandeln einer ganzen Warehouse-Tabelle auf gut Glück.

Der Dateifuß, der Parquet selbstbeschreibend macht, kommt nicht mit. Spaltennamen überstehen die Umwandlung als Schlüssel, sonst nichts — nicht die deklarierten Typen, nicht die Nullbarkeit, nicht die Kompression, nicht die Statistiken pro Zeilengruppe, keine von einer Erzeugerin oder einem Erzeuger geschriebenen Zusatzangaben.

Mit DuckDB zeigt `DESCRIBE SELECT * FROM 'datei.parquet'` das Schema in einer Zeile und in wenigen Sekunden, und zu wissen, welche Spalte INT64 statt DOUBLE war, erklärt hinterher das meiste, was am JSON zunächst merkwürdig wirkt. Ohne DuckDB helfen ein paar umgewandelte Beispielzeilen genauso — die Anführungszeichen um große Zahlen, die ISO-Zeichenketten und die maskierten verschachtelten Spalten verraten jeweils, welcher Typ dahintersteckt.

In diesem Browser-Tab. Ein in reinem JavaScript geschriebener Parquet-Leser wird beim ersten Gebrauch dieser Seite nachgeladen und arbeitet danach lokal; die Datei selbst geht nirgends hin, und der Netzwerk-Tab zeigt während der Umwandlung den Leser ankommen und nichts abgehen.

Das zählt bei diesem Format mehr als bei den meisten anderen, weil eine Parquet-Datei fast immer ein Warehouse-Artefakt ist — Kundendaten, Bestellungen, Ereignisprotokolle, Gehaltslisten. Solche Dateien kommen normalerweise über ein Datenteam, das einen Upload melden müsste. Hier gibt es nichts zu melden.