CSV in NDJSON umwandeln

Wer mit Lohn- oder Finanzbuchhaltungsdaten aus DATEV arbeitet, kennt das Muster: Jeden Monat ein neuer CSV-Export, und im April kommt eine Spalte dazu, weil eine neue Kostenstelle eingeführt wurde. Die Januar-Datei hat vierzehn Spalten, die Mai-Datei fünfzehn, und ein simples Aneinanderhängen der Dateien setzt eine fremde Kopfzeile mitten in die Datenreihen.

Genau das löst NDJSON, ohne dass jemand die Spalten vorher angleichen muss. Jede Zeile trägt ihre eigenen Feldnamen, also stört es nicht, wenn eine Zeile ein Feld mehr oder weniger hat als die nächste. Die zwölf Monatsdateien werden einzeln umgewandelt, mit `cat` zusammengefügt, und die unterschiedliche Spaltenanzahl wird zu einer Eigenschaft einzelner Datensätze statt zu einem strukturellen Problem.

Eine CSV nennt ihre Spalten einmal, ganz oben, und jede Zeile danach ist positionsabhängig — das dritte Feld ist die Kostenstelle, weil die dritte Überschrift das so festgelegt hat. NDJSON macht das Gegenteil: Jede Zeile ist ein vollständiges Objekt mit eigenen Schlüsseln, sodass der zehntausendste Datensatz für sich genommen genauso verständlich ist wie der erste.

Dafür wird bezahlt. Die Feldnamen in jeder einzelnen Zeile zu wiederholen macht die Datei größer, mitunter deutlich, wenn die Werte kurz und die Überschriften lang sind. Was man dafür bekommt: Keine Zeile hängt mehr von einer anderen ab, und genau das macht jede weitere Eigenschaft dieser Seite überhaupt erst möglich.

Weil ein Datensatz genau dort endet, wo die Zeile endet, kann die Datei an jedem Zeilenumbruch geschnitten werden, und beide Hälften bleiben gültig. `split -l 50000` erzeugt ladbare Häppchen, `head -n 500` liefert eine Stichprobe, mit der sich ein Schema tatsächlich testen lässt, und ein abgebrochener Import lässt sich ab einer Zeilennummer fortsetzen statt von vorn.

Anhängen funktioniert aus demselben Grund: Neue Datensätze kommen mit `>>` ans Ende, ohne dass darüber irgendetwas neu geschrieben werden muss. Bei einer CSV muss man dafür prüfen, ob eine Kopfzeile vorhanden ist, ob die Spaltenreihenfolge übereinstimmt und ob die letzte Zeile mit einem Zeilenumbruch endet — und ein Fehler dabei beschädigt die Datei still statt mit einer Fehlermeldung.

JSON unterscheidet die Zahl 7 von der Zeichenkette „7", eine CSV tut das nicht — also muss etwas entscheiden, und was entscheidet, ist eine Vermutung über den Text. Was wie eine Zahl aussieht, wird eine JSON-Zahl, `true` und `false` werden Wahrheitswerte, alles andere bleibt Zeichenkette.

Für Mengen und Beträge ist die Vermutung fast immer richtig, für Kennnummern falsch. Aus einer Kostenstelle `007` wird die Zahl `7`, und ist sie erst einmal Zahl, lässt sich die führende Null nirgends mehr zurückholen. Enthält der Export Codes statt Beträge, hilft es, sie in der Quelle eindeutig als Text zu kennzeichnen — ein Präfix, oder eine Spalte, die ohnehin schon als Text exportiert wurde. Die Faustregel: Würde man zwei Werte der Spalte niemals addieren, ist es eine Kennnummer und sollte Text bleiben.

Eine leere Zelle wird in der Ausgabe zu `null`, nicht zur leeren Zeichenkette. Bei einer Buchungszeile ohne Kostenstelle ist das ein echter Unterschied für alles, was die Datei später liest: Ein JSON-Schema, das eine Zeichenkette verlangt, weist `null` zurück, und eine Datenbankspalte, die nicht leer sein darf, nimmt die Zeile gar nicht erst an.

Was die Umwandlung nicht wissen kann, ist, ob die Zelle bewusst leer war oder ob dort schlicht nichts einzutragen war — eine CSV kennt für „nichts hier" nur eine einzige Schreibweise für beide Fälle. Ist der Unterschied wichtig, muss er vor der Umwandlung in der Quelle stehen, etwa als eigener Platzhalterwert, denn danach lässt er sich nicht mehr rekonstruieren.

Die Datei ist für `jq -c` gemacht, das sie Wert für Wert liest, ohne alles auf einmal in den Speicher zu laden. `jq -r ".kostenstelle"` über einen umgewandelten Export gibt eine Kostenstelle pro Zeile aus, `jq -s "length"` zählt die Datensätze, und ein `select`-Filter erzeugt eine kleinere NDJSON-Datei, die selbst wieder gültige Eingabe für alles Weitere ist.

Dasselbe gilt für alles, was zeilenweise liest. `grep` funktioniert direkt auf der Rohdatei, weil ein Datensatz sich nie über zwei Zeilen erstreckt und ein Treffer nie über einen Zeilenumbruch hinweg zerrissen wird. `wc -l` liefert die exakte Zeilenzahl — ein kleiner Vorteil, bis man ihn mit dem Zählen von Zeilen in einer CSV vergleicht, in der eine Adresse in Anführungszeichen einen Zeilenumbruch enthält.

Wachstum ist die Regel. Jede Zeile wiederholt die Feldnamen, jede Zeichenkette steht in Anführungszeichen, und um die Werte kommt die Zeichensetzung eines Objekts hinzu. Bei einer Tabelle mit kurzen Codes und langen Spaltenüberschriften kann sich die Datei glatt verdoppeln; bei langen Freitextfeldern fällt der Unterschied kaum auf, weil die Werte selbst den Ausschlag geben.

Komprimierung schließt einen Großteil der Lücke wieder, denn die wiederholten Feldnamen sind genau das, worin ein Komprimierer am besten ist — eine gezippte NDJSON-Datei liegt meist nah an einer gezippten CSV derselben Daten. Wenn nicht das Streamen, sondern die Größe im Ruhezustand zählt, lohnt ein Blick auf Parquet, wo die Spaltennamen einmal in einem Fußbereich stehen statt auf jeder Zeile.

NDJSON ist eine Form, kein Vertrag. Ein Zielsystem, das Zeilen aus JSON einliest, hat trotzdem Erwartungen an Feldnamen, an Datumsformate und daran, ob an einer bestimmten Stelle ein `null` erlaubt ist — nichts davon entscheidet diese Umwandlung.

Zwei Punkte fallen dabei besonders oft auf: Datumsangaben und Kennnummern. Ein Buchungsdatum in der CSV bleibt Text, also kommt genau die Zeichenkette an, die das Quellsystem geschrieben hat — steht dort `04.05.2026`, reist die Mehrdeutigkeit mit. Kennnummern können, wie oben beschrieben, zu Zahlen geworden sein. Beides ist mit einer kurzen `jq`-Zeile über die konvertierte Datei billig zu korrigieren, und deutlich teurer, wenn es erst nach dem Import auffällt.

Sowohl das Lesen der CSV als auch das Schreiben der JSON-Zeilen sind reines JavaScript, das diese Seite bei Bedarf nachlädt. Keine Anfrage trägt die Datei, sodass ein Lohnexport oder ein Buchhaltungsauszug umgewandelt werden kann, ohne bei jemand anderem eine Kopie zu hinterlassen.

Die kostenlose Stufe endet bei 100 MB je Datei, und darunter ist der Arbeitsspeicher die eigentliche Grenze: Die gesamte Tabelle wird aufgebaut, bevor etwas geschrieben wird, was den zweistelligen Megabyte-Bereich bequem erlaubt und erst kurz vor 100 MB einen Browser-Tab spürbar fordert. Für einen größeren Export ist ein streamender CSV-Leser in einem Skript das richtige Werkzeug — und da das Ziel ohnehin ein Datenstrom ist, ist genau dieses Skript oft der bessere Endzustand.

Ein gewöhnliches JSON-Array ist die bessere Wahl, wenn etwas das Ganze auf einmal einliest und ein Array erwartet — eine Konfigurationsdatei, eine Testdatenmenge, eine API-Antwort. Dort ist NDJSON schlechter als nutzlos, weil die meisten JSON-Parser spätestens bei der zweiten Zeile abbrechen.

Die CSV lohnt sich weiterzuführen, wenn das Ziel eine Tabellenkalkulation oder eine Importmaske ist, die genau diese Endung erwartet — keiner der beiden gewinnt etwas durch Zeilen. Und Parquet ist die richtige Wahl, wenn dieselben Daten wiederholt abgefragt statt einmalig eingelesen werden: Es speichert die Spaltennamen einmal, hält die Typen ausdrücklich statt geraten fest und ist auf der Festplatte ein Bruchteil der Größe.