JSON in NDJSON umwandeln

Bevor irgendetwas anderes zählt: Steht am Anfang der Datei eine eckige Klammer, wird aus jedem Element eine eigene Zeile. Steht dort etwas anderes — eine geschweifte Klammer, eine Zahl, ein Text —, wird das gesamte Dokument zu genau einer Zeile, weil NDJSON als ein vollständiger JSON-Wert pro Zeile definiert ist und ein einzelnes Objekt eben ein Wert ist.

Beides ist kein Fehler, und das Werkzeug warnt nicht davor. Die Prüfung liegt bei einem selbst: erstes Zeichen der Datei ansehen. Eine eckige Klammer liefert die gewünschte Datei. Eine geschweifte Klammer liefert eine gültige, aber sehr lange einzelne Zeile — genau ein Datensatz, wo tausende erwartet wurden.

Kaum eine API-Antwort ist ein blankes Array. Fast immer steckt es in einem Objekt mit einem einzigen Schlüssel — data, results, items —, dessen Wert das eigentliche Array ist. Bei den tabellarischen Zielen auf dieser Seite wird dieser Umschlag automatisch entfernt, weil eine Tabelle nirgendwo Platz dafür hat. Hier nicht, und genau diese Abweichung kostet Nutzern häufig eine Stunde.

Der Grund dafür ist, dass der Umschlag hier ein legitimer Datensatz sein könnte. NDJSON kann Objekte jeder Form aufnehmen, deshalb lässt sich nicht sicher unterscheiden, ob etwas ein wegwerfbarer Umschlag ist oder ein Datensatz, der zufällig eine Liste enthält — und zu raten würde still Daten kosten, wo die Vermutung falsch liegt. Die Lösung ist eine zehn Sekunden lange Handbewegung: Klammer und Schlüssel am Anfang entfernen, schließende Klammer am Ende ebenso, speichern, dann umwandeln.

Jedes andere Ziel für einen JSON-Export auf dieser Seite muss abflachen. Eine CSV-Datei, eine Tabellenkalkulation oder eine SQL-Einfügung hat keinen Platz für ein Objekt innerhalb eines Feldes, also werden Verschachtelungen zu Spaltennamen mit Punkten und Listen zu durchnummerierten Spalten.

NDJSON kennt dieses Problem nicht: Jede Zeile ist vollständiges JSON, also kommt eine Bestellung mit verschachtelter Kundenadresse und mehreren Positionen unverändert an. Wo das Ziel Bäume lesen kann — die meisten Ladeprozesse für Data-Warehouses und die meisten Log-Pipelines können das —, ist das die richtige Wahl gegenüber jeder abflachenden Umwandlung.

Jeder Datensatz wird kompakt geschrieben: keine Einrückung, keine Zeilenumbrüche innerhalb eines Datensatzes, eine Zeile ohne überflüssige Leerzeichen pro Element. War die Ausgangsdatei mit Einrückung formatiert, wird das Ergebnis merklich kleiner, obwohl nichts entfernt wurde — ein hübsch formatierter JSON-Export besteht oft mehr aus Leerraum als aus Daten.

Die Reihenfolge der Schlüssel innerhalb eines Datensatzes bleibt erhalten, und es wird nichts hinzugefügt oder entfernt. Fehlte ein Feld im Array bereits, fehlt es auch in der Zeile — NDJSON gleicht Datensätze nicht gegeneinander ab, wie es die tabellarischen Formate tun müssen, weil es keine gemeinsame Kopfzeile gibt, die aufgefüllt werden müsste.

Ein Zeilenumbruch innerhalb eines Textwerts wird innerhalb des JSON maskiert, nicht buchstäblich geschrieben — nichts in den Daten kann also einen tatsächlichen Zeilenumbruch erzeugen. Das macht die Zeilengrenze zu einer echten Garantie: Die Zeilenanzahl entspricht der Anzahl der Datensätze, und ein Werkzeug, das Zeilen abschneidet, erzeugt gültige Teilstücke.

Das ändert auch, was eine defekte Datei kostet. Ein fehlerhaftes JSON-Array liefert gar nichts — der Parser scheitert, und es lässt sich nicht sagen, welcher Datensatz schuld war. Eine fehlerhafte Zeile in einer NDJSON-Datei kostet nur diese eine Zeile, und ein Werkzeug, das sie einliest, kann die Zeilennummer nennen.

Darin liegt eine gewisse Ironie. Der ganze Vorteil von NDJSON ist, dass eine verarbeitende Stelle nie die komplette Datei im Speicher halten muss — und genau das ist hier trotzdem nötig: Ein JSON-Array gilt erst als gültig, wenn seine schließende Klammer gelesen wurde, also muss das Dokument vollständig geparst werden, bevor die erste Zeile geschrieben werden kann.

Die praktische Grenze liegt deshalb beim Arbeitsspeicher des eigenen Geräts, nicht bei einer festen Größenstufe. Wer selbst die Daten erzeugt, löst das besser an der Quelle: den Export direkt als NDJSON schreiben lassen, was in den meisten Exportwerkzeugen eine kleine Änderung ist und das Einlesen der ganzen Datei vollständig überflüssig macht.

Ein großer Teil nimmt sie direkt: Ladejobs, die auf newline-delimited JSON zeigen, DuckDB in einer FROM-Klausel, oder ein Werkzeug, das Datensätze zeilenweise verarbeitet. Für deutsche Behörden- und Statistikdaten, wie sie über GovData oder die Statistischen Ämter veröffentlicht werden, ist genau das die übliche Form, in der ein Ladeprozess sie anschließend erwartet.

Eine kleinere Gruppe will ein Protokoll statt bloßer Datensätze. Bulk-Anfragen an Elasticsearch oder OpenSearch verlangen vor jedem Dokument eine Anweisungszeile, ein Rumpf hat also doppelt so viele Zeilen wie Datensätze — diese Ausgabe ist dafür das Rohmaterial, nicht die fertige Nutzlast. Erscheint in der Formatbeschreibung ein Wort wie action, ist genau diese zusätzliche Zeile gemeint.

Nichts an dieser Umwandlung ist eine Einbahnstraße. Wird das Ergebnis zurück nach JSON umgewandelt, fügen sich die Zeilen wieder zu einem Array zusammen, und weil jede Zeile bereits ein vollständiger Wert war, entspricht das Array danach genau dem, was am Anfang stand — gleiche Datensätze, gleiche Verschachtelung, gleiche Schlüsselreihenfolge.

Das ist beim Entscheiden hilfreich, was aufbewahrt werden sollte. Dient die NDJSON-Datei nur einem einzelnen Ladevorgang, muss sie nicht archiviert werden — das JSON trägt dieselbe Information und wird von mehr Werkzeugen ohne Umweg gelesen. Kommen laufend neue Datensätze hinzu, ist NDJSON die praktischere Form, weil eine Zeile anzuhängen einfacher ist als eine schließende Klammer am Ende einer großen Datei neu zu setzen.

Nicht jede Gegenstelle profitiert. Liest ein Programm die Datei ohnehin auf einmal ein — eine Testfixtur, ein Seed-Skript, ein Request-Body, eine Konfigurationsimport-Datei —, ist ein JSON-Array das, was erwartet wird, und NDJSON fügt am anderen Ende nur einen Zusammenbau-Schritt hinzu.

Und werden die Datensätze wiederholt abgefragt statt nur einmal geladen, ist keine der beiden Formen ideal. Beide wiederholen jeden Schlüssel bei jedem Datensatz, was bei einer echten Datei einen großen Teil der Bytes ausmacht. Ein spaltenorientiertes Format speichert dieselben Zeilen mit einem Bruchteil des Platzes und beantwortet eine Zwei-Feld-Frage, indem es nur zwei Felder liest.

Direkt im Browser-Tab, in reinem JavaScript, ohne Upload und ohne Konto. Die kostenlose Stufe nimmt Dateien bis 100 MB an, darüber hinaus ist der Arbeitsspeicher die Grenze, nicht irgendeine Vorgabe von uns.

Der Datenschutzaspekt ist bei dieser Umwandlung sehr konkret. Dateien, die für einen Massenimport vorbereitet werden, sind häufig Ereignisprotokolle, Bestellhistorien oder Nutzerdatensätze — sie einem Webdienst zu geben, nur damit die eckigen Klammern verschwinden, wäre ein bemerkenswerter Tausch. Hier verlässt nichts das Gerät, was sich im Netzwerk-Reiter der Entwicklerwerkzeuge in Sekunden nachprüfen lässt.