XLSX in NDJSON umwandeln

In vielen mittelständischen Betrieben liegt die maßgebliche Produktliste, der Kundenexport oder die Lagerbestandsübersicht noch immer in einer Excel-Datei aus dem ERP-System, während die Zielsysteme — ein Elasticsearch-Index für die interne Suche, eine Ladeaufgabe in ein Data-Warehouse, ein Warteschlangen-Produzent — Datensätze einzeln erwarten, nicht als ein großes Dokument.

Genau dafür gibt es NDJSON: ein JSON-Objekt je Zeile statt eines einzigen Arrays. Für die IT-Abteilung bedeutet das, den Excel-Export als Zwischenschritt einmal richtig umzuwandeln, statt bei jedem Import ein eigenes Skript zu pflegen.

Ein JSON-Array ist ein einziger Wert. Um das letzte Objekt darin zu lesen, muss vorher alles davor geparst worden sein — entweder im Arbeitsspeicher komplett oder mit einem streamenden Parser, der Teilstrukturen versteht. Bei einer Konfigurationsdatei spielt das keine Rolle, bei vier Millionen Zeilen entscheidet es darüber, ob der Import läuft oder das Betriebssystem den Prozess beendet.

Zeilenweises JSON entfernt das Problem, indem es den umschließenden Container weglässt. Jede Zeile ist ein vollständiger, unabhängiger Wert, ein Konsument liest eine Zeile, verarbeitet sie, verwirft sie und macht weiter — mit konstantem Speicherbedarf. Genau das macht ein Ladejob wieder wiederaufnehmbar: Bricht der Import bei Datensatz achthunderttausend ab, lässt er sich ab dieser Zeile fortsetzen, während ein nicht mehr parsbares Dokument gar nichts mehr hergibt.

Die Garantie gilt nur, wenn nichts in den Daten selbst einen Zeilenumbruch erzeugen kann, und genau das stellt diese Umwandlung sicher. Ein Zellinhalt mit einem eingebauten Zeilenumbruch — eine mehrzeilige Lieferadresse, ein mit Alt+Enter eingegebener Kommentar — wird als Escape-Sequenz innerhalb der JSON-Zeichenkette geschrieben, sodass der Datensatz auf einer Zeile bleibt.

Das ist der handfeste Vorteil gegenüber einer tabulatorgetrennten Datei: Dort muss eine problematische Zelle in Anführungszeichen verpackt werden, und jedes lesende Werkzeug muss diese Konvention richtig umsetzen. Hier gibt es nichts umzusetzen — jeder JSON-Parser versteht die Escape-Sequenz, und kein Shell-Werkzeug scheitert an einem Tabulatorzeichen mitten in einer Adresse.

Eine tabulatorgetrennte Datei kennt nur einen Typ: Text. Was sie einliest, muss raten, und genau beim Raten werden aus Kennnummern Ganzzahlen und aus Versionsnummern Dezimalwerte. JSON trägt die Unterscheidung ausdrücklich: eine Menge wird als `12` geschrieben, ein Schalter als `true`, ein leerer Wert als `null`, ein als Text formatierter Artikelcode bleibt in Anführungszeichen mit seinen führenden Nullen.

Für eine Ladung in ein typisiertes Zielsystem ist das echte Zeit wert: Das deklarierte Schema und die gelieferten Werte stimmen ohne eine Zwischenschicht überein, und ein Ladejob, der eine Zeile ablehnt, nennt das betroffene Feld statt nur eine Fehlermeldung zu einer Zeilennummer auszugeben — vorausgesetzt, die Excel-Datei hatte die Zellen entsprechend formatiert.

Jede Zeile wiederholt jeden Feldnamen. Fünfzigtausend Zeilen mit sechs Spalten bedeuten fünfzigtausend Kopien derselben sechs Feldnamen — an einer realen Tabelle kamen dabei etwa 4,4 MB gegenüber 1,8 MB für dieselben Daten als tabulatorgetrennter Text zusammen, ungefähr das Zweieinhalbfache.

Für dieses Ziel ist der Aufpreis meist gerechtfertigt, weil die Datei einmal maschinell gelesen wird und nicht dauerhaft so gespeichert bleibt. Sollen dieselben Datensätze wiederholt abgefragt werden, ist eine spaltenorientierte Form die richtige Wahl, und dieselbe Tabelle landet dort bei einem Bruchteil der Größe. NDJSON ist ein Transportformat, kein Speicherformat — und für die Übertragung spielt die Größe ohnehin kaum eine Rolle, weil sich die wiederholten Schlüssel hervorragend komprimieren lassen.

Nicht jede API, die von zeilenweisem JSON spricht, meint damit nur das. Elasticsearch- und OpenSearch-Bulk-Anfragen verschachteln vor jedem Dokument eine Anweisungszeile, der Rumpf besteht also aus doppelt so vielen Zeilen wie Datensätzen, und diese Ausgabe ist dafür das Rohmaterial, nicht schon die fertige Anfrage. Die Anweisungszeilen zu erzeugen ist wenige Zeilen Skript über der Datei.

Ladejobs, die das Format direkt entgegennehmen, sind der häufigere Fall: eine Warehouse-Ladung, ein Warteschlangen-Produzent, der eine Nachricht je Zeile liest, die eigene Importroutine einer Anwendung. Ein Blick in die Dokumentation des Zielsystems klärt, ob dort von einer Anweisungszeile oder einem Metadatenfeld die Rede ist — dann ist ein Protokoll gemeint, und diese Datei ist nur dessen Nutzlast.

Ein Datum in einer Excel-Tabelle ist eine Zahl, die Tage seit einem festen Ursprung zählt, mit einer Anzeigeformatierung darüber — die Umwandlung schreibt den Wert, nicht das Erscheinungsbild: Der 1. Januar 2024 wird zu 45292, ein Zeitstempel bekommt einen Bruchteil für die Uhrzeit dazu.

Genau das ist der Fehler, auf den man bei diesem Ziel achten sollte, weil JSON-Zahlen gültig sind und ein Ladejob mit einer numerischen Spalte 45292 klaglos annimmt und nichts meldet. Solche Felder gehören bewusst in die Umwandlung eingeplant — in einem jq-Schritt über der Datei oder im Zielsystem nach dem Laden — statt Wochen später in einem Dashboard aufzufallen.

Eine leere Zelle wird als `null` geschrieben statt weggelassen, sodass jedes Objekt dieselben Schlüssel trägt und ein Konsument, der eine feste Form erwartet, sie bekommt. Führen spätere Zeilen ein Feld ein, das frühere nicht hatten, ist die Schlüsselmenge die Vereinigung über die ganze Tabelle — nichts fällt weg, nur weil es spät auftaucht.

Umgewandelt wird nur das erste Arbeitsblatt, weil ein Strom von Datensätzen keine Möglichkeit hat, „und jetzt eine andere Tabelle" auszudrücken. Steht die benötigte Tabelle nicht an erster Stelle, hilft es, die Mappe umzusortieren und erneut umzuwandeln; braucht man mehrere, wandelt man mehrfach um und lädt die Ergebnisse als getrennte Ströme, was das Zielsystem ohnehin erwartet.

Alles läuft im Browser. Die Mappe wird eingelesen und die Zeilen werden lokal geschrieben, ohne Upload und ohne Warteschlange — für einen Export mit Kundendaten, Bestellungen oder etwas, das einer betrieblichen Datenschutzvorgabe unterliegt, ist das der Unterschied zwischen einem Werkzeug, das im Betrieb eingesetzt werden darf, und einem, das es nicht darf.

Die Obergrenze liegt bei 100 MB je Mappe und 100 Dateien je Ablage, für alle gleich und keine bezahlte Stufe darüber. Deutlich vor diesem Wert macht sich der Arbeitsspeicher bemerkbar, weil die Tabelle vor dem Schreiben als Array eingelesen wird: Einige Dutzend Megabyte sind unauffällig, nahe der Obergrenze beginnt ein Browser-Tab zu ächzen. Darüber hinaus ist ein streamender Leser in einem Skript das richtige Werkzeug, und das rechtzeitig zu sagen ist ehrlicher, als bei einer sehr großen Datei auf halber Strecke stehenzubleiben.

Liest ein Konsument die gesamte Datei auf einmal und reicht sie weiter — ein Fixture, ein Seed-Skript, ein Anfragekörper —, ist ein JSON-Array die erwartete Form, und NDJSON würde nur einen zusätzlichen Zusammenbau-Schritt hinzufügen. In diesem Fall lieber direkt zu JSON umwandeln.

Werden die Datensätze wiederholt abgefragt statt einmal geladen, ist Parquet das bessere Ziel: dieselben Zeilen, ein Bruchteil der Bytes, und eine Abfrage, die zwei Felder braucht, liest auch nur zwei Spalten statt jeder Zeile. NDJSON ist die richtige Antwort, solange Daten in Bewegung sind, und die falsche, sobald sie angekommen sind.