NDJSON en JSON

Transformez du JSON délimité par des sauts de ligne en un seul tableau. Chaque ligne est analysée indépendamment, et toute ligne en échec est signalée avec son numéro plutôt que d’emporter tout le fichier.

Le NDJSON est ce que produisent les chaînes de journalisation, les exports BigQuery, les fichiers bulk d’Elasticsearch et les API en flux, et c’est ce qui provoque les erreurs « Extra data » et « unexpected non-whitespace character » quand on l’analyse comme un document unique.

Ce qu’est le NDJSON

Une valeur JSON complète par ligne, séparées par un saut de ligne. Pas de virgules entre les enregistrements, pas de tableau englobant. Les lignes vides sont ignorées. Les extensions habituelles sont .ndjson et .jsonl.

JSON Lines et NDJSON sont en pratique le même format, décrit par deux petites spécifications qui s’accordent sur tout ce qui compte. Certains outils nomment l’un, d’autres l’autre ; un fichier écrit pour l’un est lu correctement par les deux.

Pourquoi il existe

Trois avantages réels, qui découlent tous de l’indépendance des enregistrements.

Il se diffuse en flux

Le consommateur traite un enregistrement à la fois et ne détient jamais tout le fichier. Un export de 50 Go passe ; un tableau JSON de 50 Go, non.

Il s’ajoute à la fin

Ajouter un enregistrement est une seule écriture en fin de fichier. Ajouter à un tableau JSON suppose de réécrire le crochet fermant, ce qui n’est pas un ajout du tout.

Il survit à la corruption

Une ligne malformée vous coûte un enregistrement. Un octet malformé dans un tableau JSON vous coûte le fichier.

Dans quel sens convertir

Vers un tableau quand les données partent là où l’on attend un document unique : un navigateur, un corps de requête, un fichier de configuration. Vers du NDJSON quand elles partent dans une chaîne de traitement, un journal, un fichier en ajout seul ou tout ce qui se diffuse en flux. Les deux sens sont disponibles ci-dessus.

How to do this in code

Lire et écrire du NDJSON en code.

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
}

Questions fréquentes

NDJSON et JSON Lines, est-ce la même chose ?

À toutes fins pratiques, oui. Ce sont deux petites spécifications qui s’accordent sur l’essentiel : une valeur JSON par ligne, UTF-8, séparées par des sauts de ligne. Les extensions .jsonl et .ndjson s’emploient indifféremment.

Un enregistrement peut-il tenir sur plusieurs lignes ?

Non. C’est tout l’intérêt du format : le saut de ligne est le séparateur d’enregistrements, chaque enregistrement doit donc tenir sur exactement une ligne. Minifiez chaque enregistrement avant de l’écrire.

Pourquoi mon fichier NDJSON échoue-t-il à s’analyser comme du JSON ?

Parce que ce n’est pas un document JSON, mais plusieurs. JavaScript signale « Unexpected non-whitespace character after JSON » et Python signale « Extra data ». Les deux veulent dire que l’analyseur a terminé une valeur et en a trouvé une autre.