Padroneggiare i file JSONL: struttura, casi d'uso e vantaggi principali

Un file JSONL contiene un valore JSON completo per riga. La documentazione ufficiale lo definisce "il formato di testo JSON Lines, chiamato anche JSON delimitato da nuova riga". Questa singola regola è il motivo per cui si trasmette bene in streaming, sopravvive alle letture parziali e non si apre con un foglio di calcolo.

Cos'è un file JSONL?

JSON Lines è un formato di testo per i record. La specifica lo descrive come "un formato pratico per memorizzare dati strutturati che possono essere elaborati un record alla volta".

La documentazione è esplicita sulla sua collocazione. "Funziona bene con gli strumenti di elaborazione di testo in stile Unix e con le pipeline di shell", e la pagina aggiunge che "è un ottimo formato per i file di log". Viene anche descritto come "un formato flessibile per il passaggio di messaggi tra processi cooperanti".

Il contrasto con il semplice JSON è il punto cruciale. Un array JSON di un milione di record è un unico valore: un lettore deve consumare l'intero file prima che la struttura sia completa. Un file JSONL di un milione di record è composto da un milione di valori, e ogni riga è indipendente.

Esiste una seconda specifica strettamente correlata. La specifica NDJSON è diretta al riguardo: "al momento non esiste uno standard per il trasporto di istanze di testo JSON all'interno di un protocollo di streaming". Il suo caso d'uso dichiarato è "la distribuzione di più istanze di testo JSON attraverso protocolli di streaming come TCP o pipe UNIX".

Come è strutturato un file JSONL

I tre requisiti

La documentazione di JSON Lines ne elenca esattamente tre. Il primo è la codifica UTF-8. Comporta un avvertimento mutuato dallo stesso JSON: "come per lo standard JSON, NON deve essere incluso un indicatore dell'ordine dei byte (BOM, U+FEFF)".

Il secondo è che ogni riga deve essere un valore JSON valido. La pagina osserva che "i valori più comuni saranno oggetti o array, ma è consentito qualsiasi valore JSON". Fornisce poi il caso limite che trae in inganno le persone: "null è un valore valido, ma una riga vuota no".

Il terzo è che il terminatore di riga è \n. Le interruzioni di riga di Windows funzionano comunque. Il motivo fornito è di natura meccanica: "questo significa che è supportato anche \r\n perché lo spazio vuoto circostante viene implicitamente ignorato durante l'analisi dei valori JSON".

Cosa non deve apparire all'interno di una riga

Questo è il vincolo che fa funzionare il formato. La specifica NDJSON lo stabilisce come requisito: "i testi JSON NON DEVONO contenere nuove righe o ritorni a capo".

Normalmente a un valore JSON è consentito estendersi su più righe con rientri. In un file delimitato da righe questo non è possibile, perché la nuova riga funge da separatore di record. Ogni record deve essere scritto su un'unica riga fisica.

La riga finale e le righe vuote

Due dettagli differiscono tra le due specifiche, ed entrambi sono importanti quando un file viene rifiutato.

Consideriamo la nuova riga finale. JSON Lines afferma che "includere un terminatore di riga dopo l'ultimo valore JSON in un file è fortemente raccomandato ma non richiesto".

Sulle righe vuote le due specifiche non concordano. JSON Lines è rigido: una riga vuota non è un valore valido. NDJSON è permissivo, consentendo che "il parser PUÒ ignorare silenziosamente le righe vuote", richiedendo però che "questo comportamento DEVE essere documentato".

Estensioni e tipi di media

Anche la denominazione si divide. JSON Lines afferma che i file "possono essere salvati con l'estensione di file .jsonl". Riguardo al tipo di media, dichiara che "il tipo MIME può essere application/jsonl, ma questo non è ancora standardizzato". NDJSON afferma che il tipo di media "DOVREBBE essere application/x-ndjson" e l'estensione "DOVREBBE essere .ndjson".

Per la compressione, JSON Lines consiglia compressori di flusso: "gzip o bzip2 sono raccomandati per risparmiare spazio, generando file .jsonl.gz o .jsonl.bz2".

Vale la pena conoscere una piccola convenzione quando si legge un messaggio di errore. Gli editor di testo chiamano la prima riga "riga 1". La documentazione estende questo concetto: "anche il primo valore in un file JSON Lines dovrebbe essere chiamato 'valore 1'".

A cosa serve il formato JSONL

In genere ci si imbatte in un file .jsonl in una di queste quattro situazioni.

File di log e di eventi. La documentazione stessa del formato menziona i file di log, e il motivo è che un sistema di scrittura può aggiungere una riga alla volta senza dover riscrivere nulla.

Caricamenti in data warehouse. La documentazione di BigQuery di Google è un buon esempio del riconoscimento ufficiale del formato. Supporta il caricamento di "dati JSON delimitati da nuova riga (ndJSON) da Cloud Storage", e il suo selettore di formato file elenca l'opzione come "JSONL (JSON delimitato da nuova riga)".

Esportazioni API di record nidificati. I dati che non si appiattiscono in modo pulito in colonne mantengono la loro nidificazione riga per riga. Le righe d'ordine con un numero variabile di articoli sono il caso classico.

Dataset di machine learning. I set di addestramento e valutazione sono comunemente distribuiti in questo modo, perché un ciclo di addestramento legge i record uno alla volta.

Il filo conduttore è lo streaming. Diventa la scelta ovvia quando il file viene prodotto o consumato in modo incrementale.

Confronto tra JSONL, JSON e CSV

	JSONL	JSON	CSV
Unità del file	Un valore per riga	Un valore per l'intero file	Una riga per riga
Dati nidificati	Sì, per record	Sì	Non nativamente
Aggiungere un record	Aggiungere una riga	Riscrivere il contenitore	Aggiungere una riga
La lettura parziale è utile	Sì	Raramente	Sì
Si apre in un foglio di calcolo	No	No	Di solito
I record possono avere strutture diverse	Sì	Sì	No, le colonne sono fisse
Leggibile dall'uomo in un editor	Sì, una riga lunga per ciascuno	Sì, se rientrato	Sì

La riga che sorprende di più è la penultima. Due righe nello stesso file JSONL possono contenere chiavi diverse. Questo è esattamente ciò che rende il formato flessibile, ed è esattamente ciò che fa sì che un'importazione ingenua produca colonne irregolari.

Per l'alternativa binaria orientata alle colonne, la guida a Parquet copre lo stesso territorio dal punto di vista dell'archiviazione. Per il caso tabellare più semplice, l' analisi di TSV tratta il testo separato da tabulazioni.

Vantaggi chiave

Scrittura di tipo append-only. Un nuovo record corrisponde a una nuova riga. Nulla di quanto scritto in precedenza nel file deve cambiare.

Letture in streaming. Un consumatore può elaborare il primo record prima ancora che sia stato scritto il record numero due milioni.

Tolleranza ai guasti. Un file troncato è comunque leggibile fino all'ultima riga completa. Un array JSON troncato è solitamente del tutto illeggibile.

La nidificazione si conserva. La struttura che un CSV dovrebbe appiattire rimane intatta all'interno di ciascun record.

Adatto alla shell. La documentazione ne attribuisce il merito all'elaborazione di testi in stile Unix e alle pipeline di shell, poiché un file orientato alle righe funziona con strumenti orientati alle righe.

Supporto per i data warehouse. La documentazione di BigQuery stabilisce la regola che applica: "ciascun oggetto JSON deve trovarsi su una riga separata nel file".

Dove il formato JSONL smette di essere utile

Il formato risolve il trasporto e l'aggiunta di dati. Non risolve nessuna delle domande che potreste avere sul contenuto.

La compressione rappresenta un vero e proprio compromesso piuttosto che un vantaggio gratuito. La documentazione di BigQuery è categorica sul costo: "se si utilizza la compressione gzip, BigQuery non può leggere i dati in parallelo". Aggiunge che "il caricamento di dati JSON compressi in BigQuery è più lento rispetto al caricamento di dati non compressi". La pagina stessa del formato raccomanda gzip per risparmiare spazio. Entrambe le cose sono vere e spingono in direzioni opposte.

È anche logorroico. Ogni riga ripete il nome di ogni chiave, quindi un set di record ampio è sostanzialmente più grande rispetto agli stessi dati in un formato colonnare.

E non dice nulla sulla coerenza. Sono ammessi record con strutture diverse, il che significa che un campo può smettere silenziosamente di apparire a metà di un file senza che nulla risulti non valido.

Come lavorare con un file JSONL se non si è ingegneri

Questo è il divario pratico. Gli strumenti aziendali si aspettano righe e colonne, e un file .jsonl non si aprirà come fa un CSV.

La via pragmatica è una fase di conversione. Chiedete a chi ha prodotto il file un estratto CSV o Excel appiattito dei campi necessari. Oppure appiattitelo voi stessi con qualsiasi strumento in grado di gestire il formato JSON. In questo modo si perde la nidificazione, il che di solito non ha importanza una volta deciso quali campi utilizzare per l'analisi.

Da lì in poi, il lavoro è una normale analisi. La pagina dei prezzi di Powerdrill Bloom elenca i caricamenti per Excel, CSV, PDF e documenti, quindi un estratto appiattito viene inserito direttamente. Le domande vengono poste in linguaggio naturale anziché essere scritte come query. L' assistente AI per CSV copre questo percorso, e i connettori dati coprono i casi in cui è preferibile estrarre i dati direttamente dalla fonte piuttosto che esportarli.

La distinzione che vale la pena ricordare è che si tratta di una decisione di trasporto presa a monte. Convertire il file una volta arrivato sulla vostra scrivania è normale, non un ripiego.

Conclusione

JSONL è un formato di testo con un'unica regola: un valore JSON completo per riga e nessuna nuova riga all'interno di un valore. Questa regola garantisce la possibilità di aggiunta, lo streaming e la tolleranza alla lettura parziale, motivo per cui i log e i caricamenti nei data warehouse lo utilizzano come impostazione predefinita.

Ciò che non garantisce è una tabella. Nel momento in cui il file raggiunge qualcuno che ha bisogno di risposte piuttosto che di una pipeline, il passo successivo utile è un estratto appiattito e una domanda.

Se vi trovate in questa situazione, provate Powerdrill Bloom con il file convertito e iniziate a trasformarlo in un grafico.

Domande frequenti

A cosa serve un file JSONL?

Viene utilizzato per i flussi di record: file di log, esportazioni di eventi, caricamenti in data warehouse e dataset di machine learning. La documentazione del formato menziona specificamente i file di log e le pipeline di shell. Il fattore comune è che i record vengono scritti o letti uno alla volta.

Qual è la differenza tra JSONL e NDJSON?

Descrivono la stessa idea con formalità diverse. JSON Lines utilizza l'estensione .jsonl e rileva che application/jsonl non è ancora standardizzato. NDJSON specifica .ndjson e application/x-ndjson, e consente ai parser di ignorare le righe vuote.

Posso aprire un file JSONL in Excel?

Non facendo doppio clic su di esso, perché ogni riga è un valore JSON anziché una riga di celle. L'approccio consueto consiste nell'appiattire prima i campi necessari in CSV o Excel, oppure nell'utilizzare uno strumento che legga direttamente il formato.

Perché un record non può estendersi su più righe in JSONL?

Perché il carattere di nuova riga è il separatore di record. La specifica NDJSON stabilisce che "i testi JSON NON DEVONO contenere nuove righe o ritorni a capo". Il formato JSON formattato (pretty-printed) deve quindi essere compresso su un'unica riga per record.

È consentita una riga vuota in un file JSONL?

Le due specifiche differiscono. JSON Lines stabilisce che "null è un valore valido, ma una riga vuota no". NDJSON consente a un parser di ignorare silenziosamente le righe vuote, a condizione che tale comportamento sia documentato.