NDJSON in TSV umwandeln

Der Fall ist meist derselbe: Ein Team betreibt einen nächtlichen Event-Export, der irgendwann in einer Shell-Pipeline weiterverarbeitet wird — geschnitten, sortiert, verknüpft, gezählt, oder per \copy in eine PostgreSQL-Instanz geladen. Der Rohexport liegt als NDJSON vor, weil das die natürliche Ausgabe der meisten Logging- und Analyse-Systeme ist, und die Pipeline dahinter erwartet Tab-getrennte Zeilen statt verschachtelter Objekte.

Wer diese Datei durch eine deutsche Serverumgebung schleust, hat oft zusätzlich einen guten Grund, sie nicht bei einem fremden Dienst hochzuladen: Produktionslogs tragen IP-Adressen, Sitzungskennungen und Nutzeragenten, und genau diese Felder sind der Grund, warum die Verarbeitung besser auf dem eigenen Rechner bleibt.

Ein Blick auf einen typischen Event-Datensatz genügt. Ein Pfad mit Query-String, ein Nutzeragent, der aus lauter Kommas und Klammern besteht, eine Fehlermeldung mit einem zitierten Wert, eine Adresse. Landet das in einer CSV, steht ein großer Teil jeder Zeile in Anführungszeichen, weil das Trennzeichen praktisch in jeder Zeile im Wert selbst vorkommt.

Tabs kommen in solchen Werten fast nie vor, deshalb bleiben die meisten Felder unquotiert und die Datei positional lesbar — Spalte drei liegt tatsächlich zwischen dem zweiten und dritten Tabulator. Genau diese Eigenschaft steht im Mittelpunkt dieser Seite, und genau sie kann durch eine Handvoll Felder wieder verschwinden.

Es lohnt sich, genau zu sein, denn der ganze Reiz einer Tab-getrennten Datei liegt darin, dass die lesenden Werkzeuge einfach bleiben dürfen. Ein Wert mit einem Tabulator wird in Anführungszeichen gesetzt. Ein Wert mit einem Anführungszeichen wird gesetzt, das interne Zeichen verdoppelt. Ein Wert mit einem Zeilenumbruch wird gesetzt. Alles andere, Kommas eingeschlossen, bleibt unverändert.

Das ist die RFC-4180-Konvention mit einem Tab statt eines Kommas, nicht die IANA-Definition von Tab-getrennten Werten, die Tabs innerhalb von Feldern grundsätzlich verbietet statt sie zu escapen. In der Praxis heißt das: cut -f4 und awk -F$'\t' sind korrekt, bis eine Fehlermeldung einen Tabulator enthält — dann gewinnt diese eine Zeile ein zusätzliches Feld, und jede Spalte danach verschiebt sich, nur in dieser Zeile. Es gibt keine Fehlermeldung dazu. Wo Freitextfelder eingefügten Text tragen können, lohnt eine Prüfung, bevor eine positionale Auswertung ihr Ergebnis zurückgibt.

Die Spalten sind die Vereinigung aller Schlüssel, die irgendwo in der Datei vorkommen, in der Reihenfolge ihres ersten Auftretens. Das ist die einzig sinnvolle Antwort für eine Quelle, in der nichts garantiert, dass die zweite Zeile dieselben Schlüssel trägt wie die erste — und es ist die wichtigste Sache, die man vor der Automatisierung dieser Umwandlung verstehen sollte.

Das bedeutet: Die Spaltenreihenfolge ist eine Eigenschaft der Daten, nicht des Formats. Ein nächtlicher Export, bei dem der erste Fehler-Datensatz heute in Zeile 12 auftaucht und morgen in Zeile 40.000, erzeugt zwei Dateien mit unterschiedlicher Spaltenreihenfolge. Die Kopfzeile stimmt in beiden Fällen. Eine Pipeline, die über Namen liest, ist unbetroffen; eine, die über Position liest, ist am zweiten Tag falsch, ohne ein Anzeichen davon zu geben.

Die Lösung besteht darin, der Datei die Entscheidung wegzunehmen. Die Datensätze vor der Umwandlung auf einen festen Schlüsselsatz projizieren — jq -c '{ts, level, service, msg}' gibt jeder Zeile dieselben vier Schlüssel in derselben Reihenfolge, und die Umwandlung hat dann nur noch eine mögliche Spaltenanordnung, unabhängig davon, was die Quelle enthielt.

Das löst gleichzeitig das Problem breiter, dünn besetzter Tabellen. Ein Export mit gemischten Ereignistypen erzeugt vollständig konvertiert eine Spalte für jedes Feld, das irgendein Ereignistyp jemals trug, die meisten davon in den meisten Zeilen leer; wer vorher projiziert, bekommt eine schmale Tabelle ohne leere Zellen. Wo eine Projektion nicht möglich ist, hilft zumindest eine Prüfung: die Kopfzeile in der Pipeline lesen und laut fehlschlagen, wenn sie nicht der erwarteten entspricht, statt cut -f3 einen Monat lang das falsche Feld liefern zu lassen.

Strukturierte Logs verschachteln — ein request-Objekt mit Methode und Pfad, ein user-Objekt mit einer Kennung, ein context-Block mit einer Trace-ID. Jeder Blattwert bekommt eine Spalte, benannt nach seinem Pfad: request.method, user.id, context.trace_id. Eine Spalte je Blattwert, ohne Ausnahme.

Ein Punkt im Spaltennamen stört cut und awk nicht, die die Kopfzeile ohnehin ignorieren, ist aber überall sonst unbequem: In SQL braucht er Quotierung, und in den meisten Ladewerkzeugen ist er kein gültiger Bezeichner. Geht die TSV-Datei in eine Tabelle, lohnt sich die Umbenennung schon beim Projektionsschritt — jq -c '{method: .request.method}' liefert direkt den gewünschten Spaltennamen und erspart später ein ALTER TABLE.

PostgreSQL braucht die meiste Sorgfalt, denn sein Standard-Textformat für COPY verwendet Backslash-Escapes statt Anführungszeichen und liest ein quotiertes Feld wörtlich ein, Anführungszeichen inklusive. Die Form, die zum Geschriebenen passt, lautet \copy events FROM 'out.tsv' WITH (FORMAT csv, DELIMITER E'\t', HEADER true) — CSV-Regeln mit einem Tab als Trennzeichen.

DuckDB liest die Datei mit read_csv('out.tsv', delim='\t', header=true) und erschließt Typen aus einer Stichprobe, was praktisch ist und zugleich der Grund, warum eine Spalte mit Kennungen ihre führenden Nullen verliert — für alles, was Text bleiben muss, hilft eine explizite types-Angabe. SQLites .import --csv braucht das Trennzeichen zuvor mit .separator "\t" gesetzt. In allen drei kommt ein leeres Feld ohne weitere Angabe als leere Zeichenkette an, nicht als NULL.

Ein JSON-null und ein leerer JSON-String werden beide zu nichts zwischen zwei Tabs, und danach lässt sich keiner der beiden mehr vom anderen unterscheiden. Das liegt nicht an einer Nachlässigkeit — eine Textdatei mit Trennzeichen kennt keinen dritten Zustand.

Ob das etwas ausmacht, hängt von der Frage ab. Zu zählen, wie viele Ereignisse ohne user_id ankamen, ist eine andere Abfrage als zu zählen, wie viele mit einer leeren ankamen, und nach dieser Umwandlung liefern beide dieselbe Antwort. Ist die Unterscheidung wichtig, sollte sie vor der Umwandlung kodiert werden — jq -c '.user_id //= "«null»"' ist unschön, aber eindeutig — oder der Export geht stattdessen nach Parquet, wo null ein echter Zustand ist und die Spalte ihren Typ behält.

Meist weniger als vorher. Jede Zeile der Quelle wiederholt ihre Schlüsselnamen, die TSV-Datei schreibt sie einmal in der Kopfzeile und danach nur noch die Werte — ein schmaler Datensatz schrumpft dadurch spürbar. Ein breiter, dünn besetzter geht den umgekehrten Weg, weil jede Zeile für jede Spalte einen Tab braucht, auch dort, wo nichts steht.

Die kostenlose Obergrenze liegt bei 100 MB je Datei, und der gesamte Export wird eingelesen, bevor die Spalten feststehen — der Arbeitsspeicher wird also meist eher zur Grenze als das Limit selbst. NDJSON lässt sich an jeder Zeile gefahrlos aufteilen, split -l 500000 erzeugt Dateien, die jede für sich sauber umwandeln — allerdings können getrennt umgewandelte Teildateien aus genau demselben Grund unterschiedliche Spaltenreihenfolgen bekommen, ein weiteres Argument für die vorherige Projektion.

Öffnet später ein Mensch die Datei, ist CSV oder XLSX die bessere Wahl — eine Tabellenkalkulation liest CSV ohne Angabe des Trennzeichens, und ein Arbeitsblatt behält Kennungsspalten als Text. Geht der Export ins Data Warehouse oder in ein Archiv, ist Parquet kleiner, typisiert und hat gar kein Spaltenreihenfolge-Problem.

TSV hat genau eine Nische verdient: Das Ziel ist ein Programm, das anhand eines Zeichens trennt, und die Datei soll sich mit head lesen lassen, während der Befehl noch entsteht. Das ist eine echte und häufige Situation — aber nicht dieselbe wie „das muss in Excel funktionieren", und wer TSV aus letzterem Grund wählt, bekommt am Ende oft eine Datei, die die Tabellenkalkulation in eine einzige Spalte importiert.

Reines JavaScript in diesem Tab. Kein Upload, kein Nachladen einer Engine, kein Konto, keine tägliche Obergrenze — und der Netzwerk-Tab während einer Umwandlung zeigt das, statt dass man es glauben müsste.

Produktive Event-Exporte sind genau das Material, für das dieses Paar gedacht ist, und sie tragen IP-Adressen, Sitzungskennungen, Pfade und Nutzeragenten. Einen davon an einen gehosteten Umwandler zu schicken, ist eine Datenübermittlung an Dritte, gleich was dieser verspricht — und gerade bei Systemen, die unter der DSGVO betrieben werden, ist das ein Punkt, den man ohnehin dokumentieren müsste. Hier gibt es diese Übermittlung nicht.