Convertire JSON in NDJSON

Questo è l’intero meccanismo e vale la pena dirlo prima di qualunque altra cosa. Se il documento è un array, ogni elemento diventa una riga. Se è qualcos’altro, un oggetto, una stringa, un numero, l’intero documento diventa una riga, perché NDJSON è definito come un valore JSON completo per riga, e un singolo oggetto è un valore.

Nessuno dei due esiti è un errore e il convertitore non avviserà, quindi il controllo spetta all’utente: aprire il file e guardare il primo carattere. Una parentesi quadra aperta produce il file che si voleva. Una graffa aperta produce una singola riga molto lunga, che è NDJSON valido, viene caricato senza reclami dalla maggior parte dei consumatori, e rappresenta un record dove se ne aspettavano migliaia, ed è il tipo di sorpresa che si scopre solo quando una query torna con un risultato.

Le risposte API quasi mai sono un array nudo. Sono un oggetto con una chiave, data, results, items, records, il cui valore è l’array che si vuole. Per le conversioni tabulari di questo sito quella busta è spacchettata automaticamente, perché una tabella non ha dove metterla. Su questa coppia non lo è, e la differenza prende la gente alla sprovvista.

La ragione è che qui la busta è un record legittimo. NDJSON può contenere oggetti di qualsiasi forma, quindi non c’è modo di distinguere «una busta da scartare» da «un record che contiene un elenco», e indovinare scarterebbe silenziosamente i dati nei file in cui l’ipotesi è sbagliata. La soluzione è un edit di dieci secondi in un editor di testo: cancellare la graffa e la chiave di apertura, cancellare la graffa di chiusura, salvare, convertire. Se si fa spesso, jq con l’espressione .data fa la stessa cosa senza aprire il file, ed è il tipo di dettaglio che fa risparmiare tempo a ogni esecuzione.

Ogni altra destinazione per un’esportazione JSON deve appiattire. Un CSV, un TSV, un INSERT SQL o una colonna Parquet non hanno dove mettere un oggetto dentro un valore, quindi l’annidamento diventa nomi di colonna con punti e gli array diventano colonne numerate. NDJSON non ha questo problema: ogni riga è JSON, quindi un ordine con un indirizzo cliente annidato e cinque voci arriva completo.

Questo lo rende la conversione da scegliere quando la struttura sono i dati. Se la destinazione sa leggere JSON delimitato da a-capo, e la maggior parte dei caricatori di warehouse, produttori di code e speditori di log lo sa, si ottengono le proprietà di streaming e conteggio delle righe senza pagarle in struttura. Le conversioni appiattenti sono per le destinazioni che davvero non possono contenere un albero, e vanno usate solo quando è così.

Ogni record è scritto in modo compatto: nessuna indentazione, nessun a-capo dentro un record, una riga senza spazi per elemento. Se la sorgente era stampata in modo leggibile, il file diventa sostanzialmente più piccolo anche se nulla è stato rimosso, perché un JSON formattato è spesso più spazio bianco che dati.

L’ordine delle chiavi in ogni record è conservato, e nessuna chiave è aggiunta o tolta. Un record a cui mancava un campo nell’array manca anche sulla sua riga: NDJSON non riconcilia i record fra loro come fanno gli scrittori tabulari, e non ne ha bisogno, perché non c’è un’intestazione condivisa da riempire.

Un a-capo dentro un valore stringa è escapato dentro il JSON, non scritto letteralmente, quindi nulla nei dati può produrre un’interruzione di riga. È questo che rende il confine di riga una garanzia reale invece di una convenzione: wc -l è il conteggio dei record, split -l 50000 produce chunk validi, e head -1 mostra un record completo.

Cambia anche ciò che un file rotto costa. Un array JSON malformato non dà nulla: l’analisi fallisce e non si può dire quale record fosse responsabile. Una riga malformata in un file NDJSON costa quella riga, e il convertitore che la rilegge indicherà il numero di riga, che è la differenza tra una correzione di cinque minuti e un pomeriggio con un editor esadecimale, ed è un margine che vale la pena avere quando i file arrivano da sistemi che non si controllano.

C’è un’ironia in questa coppia che vale la pena dire con onestà. L’intero beneficio di NDJSON è che un consumatore non deve tenere l’intero file, e produrlo qui richiede esattamente quello: un array JSON non è valido finché non arriva la sua parentesi di chiusura, quindi il documento è analizzato intero prima che la prima riga possa essere scritta.

Il limite pratico è quindi la memoria propria invece di un tetto di dimensione, e un documento sulle centinaia di megabyte è dove una scheda del browser inizia a soffrire. Se si producono i dati, la soluzione è a monte, fare in modo che la sorgente emetta NDJSON in primo luogo, che è un cambio di una riga nella maggior parte degli esportatori, e che rimuove l’analisi dell’intero file dalla pipeline per sempre.

Un buon numero lo prende direttamente: i job di carico di BigQuery e Snowflake puntati a JSON delimitato da a-capo, DuckDB che legge il file in una clausola FROM, ClickHouse con il suo formato JSONEachRow, e la maggior parte delle routine di importazione applicative che descrivono il loro input come un oggetto per riga.

Un set più piccolo vuole un protocollo invece dei record. Le richieste bulk di Elasticsearch e OpenSearch alternano una riga di istruzione prima di ogni documento, quindi un corpo ha il doppio delle righe dei record e questo output è la materia prima invece del payload. Il modo per capire con quale dei due si ha a che fare è cercare la parola action o metadata nella descrizione del formato, e se compare, viene chiesto di generare le righe extra, ed è una distinzione che vale la pena conoscere prima di configurare la pipeline.

Niente di questa conversione è a senso unico. Convertire il risultato di nuovo in JSON riassembla le righe in un array, e dato che ogni riga era già un valore completo, l’array che si ottiene è l’array da cui si era partiti, gli stessi record, lo stesso annidamento, lo stesso ordine delle chiavi.

Questo vale la pena saperlo mentre si decide cosa conservare. Se NDJSON è un artefatto di trasporto per un carico, non c’è ragione di archiviarlo: il JSON è la stessa informazione e gli altri strumenti lo leggono più prontamente. Se i record continueranno ad arrivare, NDJSON è la forma migliore a lungo termine, perché accodare è una questione di aggiungere una riga invece di riscrivere una parentesi alla fine di un file grande, ed è la differenza tra una pipeline che gestisce volumi e una che si blocca.

Non ogni consumatore ne beneficia. Se la destinazione è un programma che leggerà l’intero file in una volta, un test fixture, uno script di seed, un corpo di richiesta, un import di configurazione, un array JSON è ciò che si aspetta, e NDJSON aggiunge solo un passaggio di riassemblaggio dall’altra parte.

E se i record saranno interrogati ripetutamente invece di caricati una volta, nessuna delle due forme è ideale. Entrambe ripetono ogni chiave su ogni record, che è una parte consistente di un file vero. Un formato colonnare contiene le stesse righe per una frazione dei byte e risponde a una domanda su due campi leggendo due campi, che è ciò che uno stream non può fare, ed è il calcolo che fa spostare un archivio di analisi verso Parquet indipendentemente da come ci è arrivato.

In questa scheda del browser, in JavaScript puro, senza upload e senza account. Il piano gratuito accetta fino a 100 MB, e oltre il vincolo è la memoria invece di una qualsiasi nostra politica.

Il punto sulla privacy è concreto per chiunque prepari un carico massivo. I file che vengono convertiti per l’ingest sono log di eventi, storie di ordini, record utente e tracce di audit, e affidarne uno a un servizio web per farsi togliere le parentesi sarebbe uno scambio notevole. Niente viene spedito altrove qui, il che è facile da verificare: aprire la scheda di rete e convertire un file, ed è il tipo di conferma che una volta sola basta per fidarsi.