NDJSON in JSON

Machen Sie aus zeilenweise getrenntem JSON ein einziges Array. Jede Zeile wird für sich geparst, und jede Zeile, die scheitert, wird mit ihrer Nummer gemeldet, statt die ganze Datei mitzureißen.

NDJSON ist das, was aus Log-Pipelines, BigQuery-Exporten, Elasticsearch-Bulk-Dateien und Streaming-APIs kommt - und es ist die Ursache der Fehler „Extra data“ und „unexpected non-whitespace character“, wenn man es als ein Dokument parst.

Was NDJSON ist

Ein vollständiger JSON-Wert pro Zeile, getrennt durch einen Zeilenumbruch. Keine Kommas zwischen den Datensätzen, kein umschließendes Array. Leerzeilen werden ignoriert. Die üblichen Endungen sind .ndjson und .jsonl.

JSON Lines und NDJSON sind praktisch dasselbe Format, beschrieben von zwei kleinen Spezifikationen, die sich in allem Wesentlichen einig sind. Manche Werkzeuge nennen das eine, manche das andere; eine für eines geschriebene Datei wird von beiden korrekt gelesen.

Warum es das gibt

Drei echte Vorteile, die alle daher rühren, dass die Datensätze unabhängig sind.

Es lässt sich streamen

Ein Konsument verarbeitet einen Datensatz nach dem anderen und hält nie die ganze Datei. Ein 50-GB-Export ist unproblematisch; ein 50-GB-JSON-Array nicht.

Es lässt sich anhängen

Einen Datensatz hinzuzufügen ist ein einziger Schreibvorgang ans Dateiende. An ein JSON-Array anzuhängen heißt, die schließende Klammer neu zu schreiben - was gar kein Anhängen ist.

Es übersteht Beschädigung

Eine fehlerhafte Zeile kostet Sie einen Datensatz. Ein fehlerhaftes Byte in einem JSON-Array kostet Sie die Datei.

In welche Richtung umwandeln

In ein Array, wenn die Daten irgendwohin gehen, wo ein einzelnes Dokument erwartet wird: ein Browser, ein Request-Body, eine Konfigurationsdatei. Nach NDJSON, wenn sie in eine Pipeline, ein Log, eine Append-only-Datei oder irgendetwas Streamendes gehen. Beide Richtungen finden Sie oben.

How to do this in code

NDJSON im Code lesen und schreiben.

import json

# Read
with open('events.ndjson') as f:
    records = [json.loads(line) for line in f if line.strip()]

# Write
with open('events.ndjson', 'w') as f:
    for r in records:
        f.write(json.dumps(r) + '\n')

# pandas knows the format
import pandas as pd
df = pd.read_json('events.ndjson', lines=True)

# NDJSON to an array
jq -s . events.ndjson > events.json

# An array to NDJSON
jq -c '.[]' events.json > events.ndjson

# Filter a huge NDJSON file without loading it all
jq -c 'select(.level == "error")' events.ndjson

import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

const rl = createInterface({
  input: createReadStream('events.ndjson'),
  crlfDelay: Infinity,
});

for await (const line of rl) {
  if (!line.trim()) continue;
  const record = JSON.parse(line);
  // one record at a time, constant memory
}

Häufige Fragen

Ist NDJSON dasselbe wie JSON Lines?

Für jeden praktischen Zweck ja. Es sind zwei kleine Spezifikationen, die sich in den wichtigen Punkten einig sind: ein JSON-Wert pro Zeile, UTF-8, durch Zeilenumbrüche getrennt. Die Endungen .jsonl und .ndjson werden austauschbar verwendet.

Darf sich ein Datensatz über mehrere Zeilen erstrecken?

Nein. Das ist der ganze Sinn des Formats: Der Zeilenumbruch ist der Datensatztrenner, also muss jeder Datensatz auf genau einer Zeile stehen. Minifizieren Sie jeden Datensatz vor dem Schreiben.

Warum lässt sich meine NDJSON-Datei nicht als JSON parsen?

Weil sie kein JSON-Dokument ist, sondern viele. JavaScript meldet „Unexpected non-whitespace character after JSON“ und Python meldet „Extra data“. Beides heißt: Der Parser war mit einem Wert fertig und fand noch einen.