JSONL-Dateien beherrschen: Struktur, Anwendungsfälle und entscheidende Vorteile
Eine JSONL-Datei enthält einen vollständigen JSON-Wert pro Zeile. Die offizielle Dokumentation nennt es „das JSON Lines-Textformat, auch als durch Zeilenumbruch getrenntes JSON bezeichnet“. Diese einzige Regel ist der Grund, warum es sich gut streamen lässt, warum es unvollständige Lesevorgänge übersteht und warum eine Tabellenkalkulation es nicht öffnen kann.
Was ist eine JSONL-Datei?
JSON Lines ist ein Textformat für Datensätze. Die Spezifikation beschreibt es als „ein praktisches Format zur Speicherung strukturierter Daten, die einzeln nacheinander verarbeitet werden können“.
Die Dokumentation äußert sich explizit darüber, wofür es sich eignet. Es „funktioniert gut mit Unix-artigen Textverarbeitungswerkzeugen und Shell-Pipelines“, und die Seite fügt hinzu, dass es „ein hervorragendes Format für Logdateien“ ist. Es wird zudem als „ein flexibles Format für die Übergabe von Nachrichten zwischen kooperierenden Prozessen“ beschrieben.
Der Kontrast zu einfachem JSON ist der entscheidende Punkt. Ein JSON-Array mit einer Million Datensätzen ist ein einziger Wert: Ein Parser muss das gesamte Dokument einlesen, bevor die Struktur vollständig ist. Eine JSONL-Datei mit einer Million Datensätzen besteht aus einer Million Werten, und jede Zeile steht für sich allein.
Es gibt eine zweite, eng verwandte Spezifikation. Die NDJSON-Spezifikation drückt es direkt aus: „Derzeit gibt es keinen Standard für den Transport von Instanzen von JSON-Text innerhalb eines Stream-Protokolls.“ Ihr erklärter Anwendungsfall ist die „Bereitstellung mehrerer Instanzen von JSON-Text über Streaming-Protokolle wie TCP oder UNIX-Pipes“.
Wie eine JSONL-Datei strukturiert ist
Die drei Anforderungen
Die JSON Lines-Dokumentation listet genau drei auf. Die erste ist die UTF-8-Kodierung. Sie enthält eine Einschränkung, die vom JSON-Standard selbst übernommen wurde: „Wie beim JSON-Standard darf KEINE Byte-Reihenfolgemarke (U+FEFF) enthalten sein“.
Die zweite ist, dass jede Zeile ein gültiger JSON-Wert sein muss. Auf der Seite wird angemerkt, dass „die häufigsten Werte Objekte oder Arrays sein werden, aber jeder JSON-Wert zulässig ist“. Dann wird der Sonderfall genannt, der oft zu Fehlern führt: „Null ist ein gültiger Wert, eine Leerzeile jedoch nicht“.
Die dritte ist, dass das Zeilenendezeichen \n ist. Windows-Zeilenenden funktionieren trotzdem. Der angegebene Grund ist technischer Natur: „Das bedeutet, dass \r\n ebenfalls unterstützt wird, da umgebende Leerzeichen beim Parsen von JSON-Werten implizit ignoriert werden“.
Was nicht innerhalb einer Zeile vorkommen darf
Dies ist die Einschränkung, die das Format überhaupt erst funktionsfähig macht. Die NDJSON-Spezifikation formuliert dies als Anforderung: „Die JSON-Texte DÜRFEN KEINE Zeilenumbrüche oder Wagenrückläufe enthalten“.
Ein JSON-Wert darf sich normalerweise über mehrere Zeilen mit Einrückungen erstrecken. In einer zeilenweise getrennten Datei ist dies nicht möglich, da der Zeilenumbruch als Trennzeichen für die Datensätze dient. Jeder Datensatz muss auf einer einzigen physischen Zeile geschrieben werden.
Die letzte Zeile und Leerzeilen
Zwei Details unterscheiden sich zwischen den beiden Spezifikationen, und beide spielen eine Rolle, wenn eine Datei abgelehnt wird.
Nehmen wir den abschließenden Zeilenumbruch. JSON Lines besagt, dass „das Einfügen eines Zeilenendezeichens nach dem letzten JSON-Wert in einer Datei dringend empfohlen, aber nicht erforderlich ist“.
Bei Leerzeilen sind sich die beiden Spezifikationen uneinig. JSON Lines ist streng: Eine Leerzeile ist kein gültiger Wert. NDJSON ist nachsichtig und erlaubt, dass „der Parser Leerzeilen stillschweigend ignorieren DARF“, verlangt jedoch, dass „dieses Verhalten dokumentiert werden MUSS“.
Dateiendungen und Medientypen
Auch bei der Benennung gibt es Unterschiede. JSON Lines besagt, dass Dateien „mit der Dateiendung .jsonl gespeichert werden können“. Zum Medientyp heißt es, dass der „MIME-Typ application/jsonl sein kann, dies jedoch noch nicht standardisiert ist“. NDJSON besagt, dass der Medientyp „application/x-ndjson sein SOLLTE“ und die Dateiendung „.ndjson sein SOLLTE“.
Für die Komprimierung empfiehlt JSON Lines Stream-Kompressoren: „gzip oder bzip2 werden zur Platzersparnis empfohlen, was zu .jsonl.gz- oder .jsonl.bz2-Dateien führt“.
Eine kleine Konvention ist hilfreich, wenn Sie eine Fehlermeldung lesen. Texteditoren bezeichnen die erste Zeile als „Zeile 1“. Die Dokumentation erweitert dies: „Der erste Wert in einer JSON Lines-Datei sollte ebenfalls als ‚Wert 1‘ bezeichnet werden“.
Wofür JSONL verwendet wird
Typischerweise begegnet Ihnen eine .jsonl-Datei in einer von vier Situationen.
Log- und Ereignisdateien. Die eigene Dokumentation des Formats nennt Logdateien, und der Grund dafür ist, dass ein Schreiber eine Zeile nach der anderen anhängen kann, ohne bestehende Daten neu schreiben zu müssen.
Warehouse-Ladevorgänge. Die BigQuery-Dokumentation von Google ist ein gutes Beispiel für den offiziellen Status des Formats. Sie unterstützt das Laden von „durch Zeilenumbruch getrennten JSON-Daten (ndJSON) aus Cloud Storage“, und die Dateiformat-Auswahl listet die Option als „JSONL (Newline delimited JSON)“ auf.
API-Exporte verschachtelter Datensätze. Daten, die sich nicht sauber in Spalten abflachen lassen, behalten ihre Verschachtelung pro Zeile. Bestellpositionen mit einer variablen Anzahl von Artikeln sind der klassische Fall.
Datensätze für maschinelles Lernen. Trainings- und Evaluierungsdaten werden häufig auf diese Weise verteilt, da eine Trainingsschleife Datensätze einzeln nacheinander einliest.
Der gemeinsame Nenner ist das Streaming. Es wird zur naheliegenden Wahl, wenn die Datei inkrementell erzeugt oder inkrementell konsumiert wird.
JSONL vs. JSON vs. CSV
| JSONL | JSON | CSV | |
|---|---|---|---|
| Einheit der Datei | Ein Wert pro Zeile | Ein Wert für die gesamte Datei | Eine Zeile pro Zeile |
| Verschachtelte Daten | Ja, pro Datensatz | Ja | Nicht nativ |
| Einen Datensatz anhängen | Eine Zeile hinzufügen | Den Container neu schreiben | Eine Zeile hinzufügen |
| Teilweises Lesen ist nützlich | Ja | Selten | Ja |
| Öffnet sich in einer Tabellenkalkulation | Nein | Nein | Normalerweise |
| Datensätze können sich in der Struktur unterscheiden | Ja | Ja | Nein, Spalten sind fest vorgegeben |
| Für Menschen in einem Editor lesbar | Ja, jeweils eine lange Zeile | Ja, wenn eingerückt | Ja |
Die Zeile, die am meisten überrascht, ist die vorletzte. Zwei Zeilen in derselben JSONL-Datei können unterschiedliche Schlüssel enthalten. Genau das macht das Format so flexibel, und genau das führt bei einem einfachen Import zu unregelmäßigen Spalten.
Für die spaltenorientierte binäre Alternative deckt die Parquet-Erklärung denselben Bereich aus Sicht der Speicherung ab. Für den einfachsten tabellarischen Fall behandelt die TSV-Analyse tabulatorgetrennten Text.
Wichtigste Vorteile
Schreiben im Append-Only-Verfahren. Ein neuer Datensatz ist eine neue Zeile. Nichts, was sich weiter vorne in der Datei befindet, muss geändert werden.
Streaming-Lesevorgänge. Ein Empfänger kann den ersten Datensatz bereits verarbeiten, bevor der zweimillionste Datensatz geschrieben wurde.
Fehlertoleranz. Eine abgeschnittene Datei ist bis zur letzten vollständigen Zeile weiterhin lesbar. Ein abgeschnittenes JSON-Array ist in der Regel völlig unlesbar.
Verschachtelungen bleiben erhalten. Strukturen, die bei CSV abgeflacht werden müssten, bleiben innerhalb jedes Datensatzes intakt.
Shell-freundlich. Die Dokumentation verweist auf Unix-artige Textverarbeitung und Shell-Pipelines, da eine zeilenorientierte Datei hervorragend mit zeilenorientierten Werkzeugen funktioniert.
Warehouse-Unterstützung. Die Dokumentation von BigQuery nennt die Regel, die sie erzwingt: „Jedes JSON-Objekt muss sich auf einer separaten Zeile in der Datei befinden“.
Wo JSONL an seine Grenzen stößt
Das Format löst den Transport und das Anhängen von Daten. Es löst jedoch keine der Fragen, die Sie bezüglich des Inhalts haben.
Die Komprimierung ist ein echter Kompromiss und kein reiner Gewinn. Die Dokumentation von BigQuery äußert sich unverblümt zu den Kosten: „Wenn Sie die gzip-Komprimierung verwenden, kann BigQuery die Daten nicht parallel lesen“. Sie fügt hinzu, dass „das Laden komprimierter JSON-Daten in BigQuery langsamer ist als das Laden unkomprimierter Daten“. Die eigene Seite des Formats empfiehlt gzip, um Platz zu sparen. Beides stimmt, und beide Aspekte ziehen in entgegengesetzte Richtungen.
Es ist zudem sehr redundant. Jede Zeile wiederholt jeden Schlüsselnamen, sodass ein breiter Datensatz erheblich größer ist als dieselben Daten in einem spaltenbasierten Format.
Und es sagt nichts über die Konsistenz aus. Datensätze mit unterschiedlichen Strukturen sind zulässig, was bedeutet, dass ein Feld ab der Hälfte einer Datei einfach nicht mehr auftauchen kann, ohne dass die Datei dadurch ungültig wird.
Wie man mit einer JSONL-Datei arbeitet, wenn man kein Entwickler ist
Dies ist die praktische Lücke. Business-Tools erwarten Zeilen und Spalten, und eine .jsonl-Datei lässt sich nicht so einfach öffnen wie eine CSV-Datei.
Der pragmatische Weg führt über einen Konvertierungsschritt. Bitten Sie den Ersteller der Datei um einen abgeflachten CSV- oder Excel-Export der von Ihnen benötigten Felder. Oder flachen Sie die Datei selbst mit einem beliebigen JSON-kompatiblen Tool ab. Dabei geht die Verschachtelung verloren, was jedoch meist keine Rolle mehr spielt, sobald Sie sich entschieden haben, welche Felder für die Analyse benötigt werden.
Ab diesem Punkt ist die Arbeit eine ganz normale Analyse. Die Preisseite von Powerdrill Bloom listet Uploads für Excel, CSV, PDF und Dokumente auf, sodass ein abgeflachter Export direkt hochgeladen werden kann. Fragen werden in natürlicher Sprache gestellt, anstatt als Abfragen formuliert zu werden. Der CSV AI assistant deckt diesen Weg ab, und Datenkonnektoren decken die Fälle ab, in denen die Daten besser direkt aus der Quelle abgerufen als exportiert werden.
Der wichtige Unterschied, den man im Hinterkopf behalten sollte, ist, dass dies eine Transportentscheidung ist, die Ihnen vorgelagert wurde. Die Konvertierung in ein anderes Format, sobald die Datei auf Ihrem Schreibtisch landet, ist völlig normal und kein Notbehelf.
Fazit
JSONL ist ein Textformat mit einer einzigen Regel: ein vollständiger JSON-Wert pro Zeile und keine Zeilenumbrüche innerhalb eines Wertes. Diese Regel ermöglicht das einfache Anhängen von Daten, Streaming und die Toleranz gegenüber unvollständigen Lesevorgängen, weshalb Logs und Warehouse-Ladevorgänge standardmäßig darauf setzen.
Was man damit jedoch nicht erhält, ist eine Tabelle. In dem Moment, in dem die Datei jemanden erreicht, der Antworten statt einer Pipeline benötigt, ist der sinnvollste nächste Schritt ein abgeflachter Export und eine Frage.
Wenn Sie sich an diesem Punkt befinden, probieren Sie Powerdrill Bloom mit der konvertierten Datei aus und beginnen Sie damit, sie in ein Diagramm zu verwandeln.
Häufig gestellte Fragen
Wofür wird eine JSONL-Datei verwendet?
Sie wird für Datenströme verwendet: Logdateien, Ereignisexporte, Warehouse-Ladevorgänge und Datensätze für maschinelles Lernen. Die Dokumentation des Formats nennt speziell Logdateien und Shell-Pipelines. Der gemeinsame Faktor ist, dass Datensätze einzeln nacheinander geschrieben oder gelesen werden.
Was ist der Unterschied zwischen JSONL und NDJSON?
Sie beschreiben dieselbe Idee mit unterschiedlichen Formalitäten. JSON Lines verwendet die Dateiendung .jsonl und merkt an, dass application/jsonl noch nicht standardisiert ist. NDJSON spezifiziert .ndjson und application/x-ndjson und erlaubt es Parsern, Leerzeilen zu ignorieren.
Kann ich eine JSONL-Datei in Excel öffnen?
Nicht durch einen Doppelklick, da jede Zeile ein JSON-Wert und keine Zeile aus Zellen ist. Der übliche Ansatz besteht darin, die benötigten Felder zuerst in CSV oder Excel abzuflachen oder ein Tool zu verwenden, das das Format direkt lesen kann.
Warum darf ein Datensatz in JSONL nicht über mehrere Zeilen gehen?
Weil das Zeilenumbruchzeichen das Trennzeichen für die Datensätze ist. Die NDJSON-Spezifikation besagt, dass „die JSON-Texte KEINE Zeilenumbrüche oder Wagenrückläufe enthalten DÜRFEN“. Schön formatiertes JSON muss daher auf eine einzige Zeile pro Datensatz komprimiert werden.
Ist eine Leerzeile in einer JSONL-Datei erlaubt?
Die beiden Spezifikationen unterscheiden sich. JSON Lines besagt, dass „Null ein gültiger Wert ist, eine Leerzeile jedoch nicht“. NDJSON erlaubt es einem Parser, Leerzeilen stillschweigend zu ignorieren, sofern dieses Verhalten dokumentiert ist.