JSON in Parquet umwandeln

Ein Export aus einem internen System — Bestellungen, Vorgänge, Nutzerereignisse — ist in aller Regel personenbezogen im Sinne der DSGVO, sobald irgendwo eine Kundennummer, eine IP-Adresse oder ein Name auftaucht. Bevor die Datei überhaupt bei einem Cloud-Tool landet, will die Datenschutzbeauftragte wissen, wohin sie geht und wer sie sieht.

Diese Umwandlung stellt diese Frage gar nicht erst: Der Parquet-Writer ist JavaScript, das die Seite bei Bedarf lädt, transponiert und schreibt die Datei im eigenen Browser-Tab, und keine Anfrage trägt den Export irgendwohin. Für eine erste Prüfung eines Exports, bevor er offiziell freigegeben wird, ist das oft der einzige Weg, der ohne Rückfrage beim Datenschutz auskommt.

Eine Parquet-Datei trägt ihr Schema im Fußbereich der Datei: jede Spalte hat einen Namen und genau einen Typ, und jede Zeile hält sich daran. Genau das erlaubt einer Abfrage-Engine, die Form einer zwei Gigabyte großen Datei zu kennen, ohne eine einzige Zeile gelesen zu haben — die Eigenschaft, für die das Format existiert.

Ein JSON-Array verspricht nichts dergleichen. Die Datensätze sind Objekte, jedes frei darin, welche Schlüssel es trägt, und nichts im Format verhindert, dass der vierzigste Datensatz eine Zeichenkette in einem Feld enthält, das die ersten neununddreißig als Zahl geführt haben. Die Umwandlung muss das Schema erst erfinden, das die Datei nie hatte, und jeder unangenehme Fall auf dieser Seite kommt aus genau diesem einen Satz.

Parquet hat keinen Platz für ein Objekt innerhalb einer Zelle, also wird der Datensatz vor dem Transponieren abgeflacht: Ein customer-Objekt mit einer city wird zur Spalte customer.city, mit dem Typ, den es im JSON hatte. Das ist dieselbe Abflachung, die auch die CSV-, TSV-, SQL- und XLSX-Writer dieser Seite vornehmen — bewusst so, damit ein verschachtelter Export bei allen fünf Formaten dieselben Spaltennamen ergibt.

Arrays sind der Fall, über den man nachdenken sollte, weil sie nach Position und nicht nach Namen abgeflacht werden. Ein tags-Array mit a und b wird zu zwei Spalten, tags.0 und tags.1, und die Spaltenliste ist die Vereinigung über die gesamte Datei — ein Feld, das meist zwei Einträge hat und gelegentlich vierzig, erzeugt vierzig Spalten, von denen die meisten Zeilen achtunddreißig davon leer lassen.

Wo jeder Datensatz ein flaches Objekt ist — ein Ereignisprotokoll, ein Export von Bestellungen, eine API-Antwort, die seitenweise geliefert wurde — leistet die Umwandlung genau das Gewünschte in einem Schritt. Die Schlüssel werden zu Spalten in der Reihenfolge, in der sie zuerst auftauchen, die Werte werden zu typisierten Spaltendaten, und das Ergebnis ist eine Datei, die DuckDB ohne weitere Vorbereitung abfragt.

Das deckt einen großen Teil realer JSON-Exporte ab. Ereignisdaten, Abrechnungszeilen, Formularabsendungen und die meisten paginierten Listen-Endpunkte sind flach angelegt, weil die Systeme dahinter Zeilen schreiben. Ein Datensatz, der doch verschachtelt ist, konvertiert trotzdem — er kommt nur breiter an, mit einer Punktspalte je Blattwert.

Datensätze, die sich nicht einig sind, welche Schlüssel sie haben, werden über die Vereinigung versöhnt. Ein Feld, das im ersten Datensatz vorkommt und im nächsten fehlt, erzeugt eine Spalte mit einem Nullwert in der zweiten Zeile, und ein Feld, das nur in den letzten zehn Datensätzen einer Million auftaucht, wird trotzdem zur Spalte.

Diese Abgleichung liest die gesamte Datei, bevor irgendetwas geschrieben wird — der ehrliche Preis dafür, nicht zu stichproben. Der Vorteil ist, dass ein seltenes Feld nie stillschweigend verschwindet. Nimm das Schema aus einer Umwandlung des gesamten Exports, nie aus dem kleinen Testausschnitt, mit dem eine Pipeline zuerst geprüft wurde.

JSON hat echte Typen, ein echter Vorteil gegenüber einer Umwandlung aus einer Tabellenkalkulation oder CSV: Eine Zahl kommt als Zahl an, ein Wahrheitswert als Wahrheitswert, ohne dass irgendetwas aus Zeichen erraten werden muss. Wahrheitswerte werden zu BOOLEAN, ganze Zahlen innerhalb des 32-Bit-Bereichs zu INT32, alles andere Numerische zu DOUBLE, Text bleibt Text.

Der Kollisionsfall ist, wenn Datensätze sich uneinig sind: Ein Feld, das in den meisten Datensätzen eine Zahl ist und in einigen wenigen ein Text — eine Kennung, die manche Systeme mit Anführungszeichen versehen und andere nicht —, macht die ganze Spalte zu Text, und die numerischen Werte werden als Text mitgeschrieben. Das ist Absicht: Eine Spalte, die den ersten Typ nimmt und den Rest stillschweigend zu Null macht, lädt zwar sauber, hat aber leise Werte gelöscht, die nicht passten.

Parquet kennt einen 64-Bit-Integer-Typ, und diese Umwandlung schreibt ihn nicht. Die Werte laufen durch JavaScript-Zahlen, die 53 Bit ganzzahlige Genauigkeit tragen, also wird ein Wert außerhalb des 32-Bit-Bereichs als DOUBLE geschrieben, statt eine Exaktheit vorzugaukeln, die er nicht mehr besitzt.

Für Kennungen ist das relevant, und die Lösung liegt vor der Umwandlung: Ein JSON-Export, der Bestellreferenzen als Zeichenketten schreibt, bringt sie exakt durch diese Umwandlung und landet als Textspalte — genau das, was eine Kennung ohnehin sein sollte. Ein Export, der sie als reine Zahlen schreibt, hat die Genauigkeit jenseits von sechzehn Stellen bereits verloren, bevor irgendein Konverter die Datei sieht.

Ein JSON-Export ist oft ein Objekt mit einem Schlüssel, der das Array enthält — data, results, records. Diese Ein-Schlüssel-Hülle wird automatisch aufgelöst, weil sie genau das ist, was fast jeder paginierte API-Endpunkt liefert.

Zwei Schlüssel sind der Fall, wo das aufhört. Eine Datei in der Form {"meta": {...}, "data": [...]} hat kein eindeutig bevorzugtes Array, also wird das gesamte Objekt zu einer Zeile, und die Datensätze werden nach Index hineingeflacht: data.0.id, data.1.id, so weiter für jeden Datensatz. Das Symptom ist eindeutig, sobald man es kennt — eine Parquet-Datei mit einer Zeile und mehreren tausend Spalten. Die Datei vor der Umwandlung mit jq auf das Array kürzen löst es.

Fünfzigtausend erzeugte Bestellzeilen mit sechs Feldern ergaben 207 KB als Parquet. Dieselben Daten waren 4,8 MB als kompaktes JSON und 6,8 MB in der eingerückten Form, in der die meisten Exporte tatsächlich ankommen.

Der Unterschied liegt nicht nur an der Kompression. Jeder JSON-Datensatz wiederholt jeden Schlüsselnamen, in einer Spaltendatenbank steht er dagegen einmal, im Fußbereich der Datei. Wiederkehrende Werte lassen sich hervorragend zusammenfassen, wenn sie beieinanderstehen — deshalb kosten Spalten wie Stadt oder Produktcode hier fast nichts mehr. Bei überwiegend eindeutigem Fließtext fällt die Ersparnis geringer aus.

Weil die Regeln, die diese Umwandlung befolgt — Vereinigung der Schlüssel, Auflösung eines Ein-Schlüssel-Wrappers, Abflachung nach Punktnotation — allesamt vorhersagbar sind, lässt sich das Ergebnis meist schon am Rohtext erraten, bevor überhaupt eine Datei umgewandelt wird. Den ersten und den letzten Datensatz eines großen Exports nebeneinanderzulegen zeigt oft schon, ob sich die Feldliste im Verlauf verändert hat.

Das kostet weniger Zeit, als das Ergebnis danach zu korrigieren. Ein Export, der mit zehn Feldern beginnt und mit fünfzehn endet, erzeugt fünf Spalten, die in den ersten tausend Zeilen durchgehend leer sind — kein Fehler, aber leichter zu erklären, wenn man es vorher schon wusste, statt es erst in der fertigen Parquet-Datei zu entdecken.

DuckDB liest die Datei direkt in einer FROM-Klausel, pandas mit einem einzigen Aufruf, Spark behandelt sie als native Tabelle. Die Datei beginnt und endet mit den vier Bytes PAR1 — daran erkennt sie jedes dieser Werkzeuge.

Der erste Blick sollte dem Schema gelten, nicht den ersten zehn Zeilen. Zwei Fragen beantworten fast alles: Ist eine Spalte als Text typisiert, die eigentlich numerisch sein sollte, und stimmt die Spaltenanzahl mit der Erwartung überein. Die erste verrät, welche Datensätze sich beim Typ nicht einig waren; die zweite, ob ein verschachteltes Feld oder ein Array die Datei breiter gemacht hat, als beabsichtigt.

Die Grenze der kostenlosen Nutzung liegt bei 100 MB pro Datei. Die eigentliche Grenze ist aber meist der Arbeitsspeicher, weil das gesamte Array geparst, in Spalten transponiert und geschrieben wird — die ganze Datenmenge existiert also gleichzeitig im Speicher des Tabs. Zehn bis zwanzig Megabyte sind unauffällig, mehrere hundert lassen den Tab spürbar länger arbeiten.

Jenseits dieser Größe ist ein streamender Reader in einem eigenen Skript das richtige Werkzeug, und das offen zu sagen ist besser, als bei einer großen Datei mittendrin abzubrechen. Wer den Export dagegen an eine Kollegin ohne Parquet-taugliches Werkzeug weitergeben will, ist mit einer Tabellenkalkulation besser bedient — Parquet ist binär und lässt sich nicht in einem beliebigen Editor öffnen.