Convertire CSV in NDJSON

Un CSV dà un nome alle sue colonne una volta sola, in alto, e ogni riga dopo è posizionale: il terzo campo è la città perché la terza intestazione lo diceva. NDJSON fa l’opposto: ogni riga è un oggetto completo che porta le proprie chiavi, quindi il settantamilionesimo record è intelligibile da solo quanto il primo.

Questo è il compromesso che la conversione fa, e non è gratis. Ripetere i nomi delle chiavi su ogni riga rende il file più grande, a volte in modo consistente su una tabella di valori brevi con intestazioni lunghe. Quello che si compra è che nessuna riga dipende da nessun’altra riga, il che è ciò che rende possibili tutte le altre proprietà di questa pagina.

La ragione per cui di solito si chiede questa conversione non è l’eleganza. È che avete undici export mensili, il sistema ha aggiunto un campo ad aprile, e non c’è modo di concatenare un file con quattordici colonne e un file con quindici. Unire i CSV lascia una riga di intestazione in mezzo ai dati, e anche rimuovendola i campi non sono più allineati.

NDJSON non ha questo problema. Record con set di chiavi diversi stanno nello stesso file in modo del tutto legittimo, e ogni consumatore ragionevole (un motore di query, un job di caricamento, uno script) tratta una chiave mancante come assente invece che come riga rotta. Convertite ogni export separatamente, concatenate i risultati con `cat`, e la differenza di schema diventa un fatto dei singoli record invece di un fallimento strutturale.

Poiché un record finisce dove finisce la riga, il file può essere tagliato ovunque ci sia un newline e entrambe le metà restano valide. `split -l 100000` produce blocchi caricabili. `head -n 1000` produce un campione che si può effettivamente eseguire contro uno schema. Un caricamento fallito può essere ripreso da un numero di riga invece di ricominciare.

L’append funziona per la stessa ragione: nuovi record vanno in fondo con `>>` e nulla sopra di loro deve essere riscritto. Fare l’equivalente su un CSV significa controllare se l’intestazione è presente, se l’ordine delle colonne corrisponde e se l’ultima riga finisce con un newline, e sbagliare uno qualsiasi di questi corrompe il file silenziosamente invece che rumorosamente.

JSON distingue il numero 7 dalla stringa «7» e un CSV non lo fa, quindi qualcosa deve decidere, e ciò che decide è l’inferenza sul testo. I valori che analizzano come numeri diventano numeri JSON (1e5 arriva nell’output come 100000), `true` e `false` diventano booleani, e tutto il resto resta una stringa.

L’ipotesi è giusta per quantità, prezzi e flag e sbagliata per identificatori. `007` diventa `7`, e una volta che è un numero nel JSON non c’è più nulla da cui recuperarlo. Se l’export contiene codici invece di misurazioni, la difesa più economica è renderli non ambigui nella sorgente: un prefisso, o una colonna già esportata come testo, entrambi sopravvivono. Il test generale è se sommare due valori nella colonna significherebbe qualcosa; in caso contrario, è un identificatore e voleva restare una stringa.

Una cella vuota viene scritta come `null` invece che come stringa vuota. È una decisione reale e vale la pena conoscerla, perché i due non sono la stessa cosa per qualsiasi cosa consumi il file: uno schema JSON con `«type»: «string»` rifiuta null, e un caricamento di database metterà un null dove vi aspettavate forse la stringa vuota che vedevate nella sorgente.

Quello che la conversione non può fare è dirvi quale dei due l’export intendesse. Un CSV ha esattamente un modo per scrivere «niente qui» e viene usato sia per «questo campo è vuoto» sia per «questo campo non si applica». Se la distinzione conta a valle, deve essere codificata nella sorgente in modo esplicito (un valore sentinella, o una seconda colonna) prima che qualsiasi conversione la veda.

Il file è progettato per `jq -c`, che lo legge un valore alla volta senza tenere il tutto in memoria. `jq -r «.city»` su un export convertito stampa una città per riga; `jq -s «length»` conta i record; un filtro `select` produce un file NDJSON più piccolo che è esso stesso ancora input valido per tutto il resto.

Lo stesso vale per qualsiasi cosa legga righe. `grep` sul file grezzo funziona ed è onesto, perché un record non può estendersi su due righe e non può essere spezzato attraverso una corrispondenza. `wc -l` dà esattamente il conteggio dei record, che è una piccola cosa finché non lo confrontate con contare le righe in un CSV dove un indirizzo tra virgolette contiene un newline.

Aspettatevi crescita. Ogni riga ripete i nomi delle chiavi, ogni stringa è quotata, e la punteggiatura di un oggetto viene aggiunta attorno ai valori. Su una tabella di codici brevi con intestazioni di colonna descrittive il file può raddoppiare; su una tabella di campi di testo libero lunghi la differenza è lieve, perché i valori dominano.

La compressione chiude la maggior parte del divario, dato che le chiavi ripetute sono esattamente ciò in cui un compressore è più bravo, e un file NDJSON gzippato di solito è vicino a un CSV gzippato degli stessi dati. Se la dimensione a riposo è ciò che conta veramente invece della forma in streaming, è un segnale per guardare invece a Parquet, dove i nomi delle colonne sono memorizzati una volta in un footer invece che su ogni record.

NDJSON è una forma di contenitore, non un contratto. Una destinazione che ingerisce JSON lines avrà comunque opinioni sui nomi dei campi, sui formati di data, e sul se un null sia permesso in una data posizione, e nessuna di queste è decisa da questa conversione.

I due che ingannano le persone sono le date e gli identificatori. Una data in un CSV è testo e resta testo, quindi qualunque stringa il sistema esportatore abbia scelto è ciò che arriva, e se quella stringa è `03/04/2024` l’ambiguità viaggia con essa. Gli identificatori, come sopra, potrebbero essere diventati numeri. Entrambi sono economici da correggere in un passaggio `jq` di una riga sul file convertito, e molto più costosi da correggere dopo il caricamento.

Leggere il CSV e scrivere le righe JSON sono entrambi semplice JavaScript, caricato da questa pagina su richiesta. Nessuna richiesta porta il file, quindi un export notturno di clienti o un estratto finanziario può essere convertito senza diventare la copia di qualcun altro.

Il livello gratuito si ferma a 100 MB per file, e sotto quel limite il tetto è la memoria. L’intera tabella è costruita prima che qualcosa venga scritto, il che mette comodamente decine di megabyte in gamma e l’ultimo tratto fino a 100 MB nel punto in cui una scheda del browser comincia a sforzarsi. Per un export più grande, un reader CSV in streaming in uno script è lo strumento appropriato, e dato che la destinazione è uno stream, scrivere quello script è spesso lo stato finale corretto comunque.

Scegliete un array JSON semplice invece quando il tutto sarà caricato in una volta da qualcosa che si aspetta un array (un payload API, una fixture di test, un file di configurazione). NDJSON è peggio che inutile lì, perché la maggior parte dei parser JSON lo rifiuterà direttamente alla seconda riga.

Mantenete il CSV se la destinazione è un foglio di calcolo o una schermata di import che lo nomina, dato che nessuno dei due guadagna qualcosa da record su righe. E scegliete Parquet quando gli stessi dati saranno interrogati ripetutamente invece che ingeriti una volta: memorizza i nomi delle colonne una volta, mantiene i tipi esplicitamente invece che per inferenza, ed è una frazione della dimensione su disco.