Convertire Parquet in JSON

Parquet è ciò che una piattaforma dati distribuisce e JSON è ciò che tutto il resto consuma. Il divario è dove vive questa conversione: una fixture che deve stare in un repository accanto al test che la legge, un file di seed per un servizio mock locale, un corpo da incollare in una richiesta mentre si capisce perché un endpoint la rifiuta, o cinquanta righe che si vogliono guardare in un visualizzatore JSON senza installare DuckDB.

Si noti che i casi interessanti sono tutti piccoli. Parquet esiste per rendere economiche le interrogazioni su tabelle molto grandi, e nulla di ciò sopravvive al viaggio — il layout colonnare, la compressione, le statistiche che permettono a un lettore di saltare interi gruppi di righe. Ciò che si ottiene è un documento di testo, e un documento di testo è l'artefatto giusto per cento righe e sbagliato per dieci milioni.

Il file Parquet viene trasposto di nuovo in righe, e quelle righe vengono scritte come un array JSON di primo livello con indentazione di due spazi e un a capo finale. I nomi delle colonne diventano chiavi dell'oggetto esattamente come li scrive lo schema, incluso qualsiasi cosa che un identificatore JavaScript non potrebbe essere.

Non c'è involucro né blocco metadati. Se la destinazione si aspetta le righe sotto un nome — `{"rows": […]}` è la forma abituale — lo si aggiunge da sé; `jq '{rows: .}'` lo fa in un passaggio. La lunghezza dell'array è il conteggio delle righe, quindi è anche il controllo di sanità più rapido che l'estratto contenga ciò che si è detto contenesse.

Questa è la sorpresa di questa pagina e vale la pena leggerla due volte. Parquet ha veri tipi nidificati — LIST, STRUCT e MAP — e il lettore qui li restituisce come oggetti JavaScript, che vengono poi serializzati in testo e messi nel campo come stringa. Una colonna `tags` con due valori non diventa `["a","b"]` nell'output. Diventa `"[\"a\",\"b\"]"`, tra virgolette, con le virgolette interne sfuggite.

Nulla viene perso e tutto è a un passo di distanza. `jq '.[0].tags[0]'` restituisce un errore su una stringa senza indici; `jq '.[0].tags | fromjson | .[0]'` restituisce il valore. Se il JSON va in una fixture di test, la mossa onesta è srotolare quelle colonne una volta con `jq 'map(.tags |= fromjson)'` e archiviare la versione strutturata, invece di lasciare una doppia codifica che chi legge la fixture dopo deve scoprire.

Una colonna timestamp di Parquet è un intero tipizzato con un'unità e un flag di fuso orario registrati nel footer. JSON non ha alcun tipo data, quindi ogni valore viene scritto come stringa ISO 8601 — `2026-03-01T08:00:00.000Z` — non ambigua, ordinabile lessicograficamente nell'ordine giusto, e compresa da `Date.parse`, `datetime.fromisoformat` e ogni controllo JSON Schema `format: date-time`.

Ciò che è sparito è la dichiarazione. Il file non dice più che la colonna è un timestamp; dice che la colonna è una stringa che sembra esserlo. Qualsiasi cosa a valle deve essere informata di nuovo — un argomento `parse_dates`, uno schema, un cast. Per una fixture va bene ed è esplicito. Per un caricamento è un altro posto dove sbagliare il fuso orario.

Parquet ha un tipo intero a 64 bit e i numeri JavaScript portano 53 bit di precisione intera. Invece di arrotondare silenziosamente, un valore che non ci sta viene scritto come stringa tra virgolette; uno che ci sta viene scritto come numero nudo.

Lo scambio è deliberato ed è nella direzione giusta — un numero d'ordine che torna sbagliato di uno è un bug che nessuno nota finché non conta, mentre una colonna che a volte è un numero e a volte una stringa è almeno visibile. Significa che una colonna può cambiare tipo a metà del file, il che renderà infelice uno schema JSON rigido. Se questa è la destinazione, si converte l'intera colonna in testo nella query che ha prodotto l'estratto e il JSON sarà coerente.

Un `BYTE_ARRAY` di Parquet senza annotazione UTF8 sono byte piuttosto che testo, e i byte non hanno rappresentazione fedele in JSON. Ogni valore simile viene scritto come stringa esadecimale minuscola — due caratteri per byte, nessun separatore, nessun prefisso.

L'esadecimale è reversibile e ovviamente non prosa, motivo per cui è stato scelto rispetto a un tentativo di decodifica. È anche il doppio della dimensione dei byte che codifica e la metà della dimensione di nulla di utile, quindi se una colonna binaria è grande e non serve, la si scarta nella query invece di portarla attraverso la conversione. Una colonna hash va bene; una colonna miniatura incorporata no.

Un valore mancante in Parquet diventa `null` nel JSON, distinto da una stringa vuota e distinto da uno zero. Sembra non notevole finché non lo si confronta con le destinazioni delimitate, dove sia null sia vuoto collassano in nulla tra due separatori e nessuna query dopo può distinguerli.

Per una fixture quella differenza è tutto il punto. Un test che verifica l'assenza di un valore ha bisogno che l'assenza sia rappresentabile, e JSON è l'unica destinazione testuale qui che la rappresenta. È anche il motivo per cui un ciclo completo attraverso JSON conserva più di un file Parquet di un ciclo attraverso CSV, anche se nessuno dei due porta lo schema.

Molto, e da tre direzioni contemporaneamente. Parquet memorizza ogni colonna una volta con il suo tipo dichiarato, poi codifica per dizionario i valori ripetuti e comprime le pagine; JSON ripete ogni nome di colonna su ogni riga, scrive ogni numero come cifre decimali, e questo output indenta ogni campo sulla propria riga.

Si pianifica per un ordine di grandezza invece che una percentuale, e di più quando la tabella è larga o i valori si ripetono molto — una colonna di stato con cinque stringhe distinte costa quasi nulla in Parquet e la sua lunghezza intera su ogni riga in JSON. L'intero documento viene anche assemblato in memoria come una stringa prima di poter essere salvato, il che è il tetto pratico ben prima del limite gratuito di 100 MB. Si prende un `LIMIT` sull'estratto invece di convertire una tabella di data warehouse sperando bene.

Il footer che rendeva il file autodescrittivo non passa. I nomi delle colonne sopravvivono come chiavi e nient'altro: non i tipi dichiarati, non la nullabilità, non la compressione, non le statistiche dei gruppi di righe, non i metadati chiave-valore che un produttore potrebbe averci scritto.

Se si ha DuckDB, `DESCRIBE SELECT * FROM 'file.parquet'` stampa lo schema in una riga di shell e richiede dieci secondi, e sapere quali colonne fossero INT64 piuttosto che DOUBLE spiega gran parte di ciò che sembra strano nel JSON dopo. Se non lo si ha, si converte una manciata di righe prima e le si legge — gli interi tra virgolette, le stringhe ISO e le colonne nidificate sfuggite dicono ciascuno quale fosse il tipo sorgente.

In questa scheda. Un lettore Parquet scritto in puro JavaScript viene scaricato la prima volta che si usa una di queste coppie e poi fa il suo lavoro localmente; il file stesso non viene mai inviato da nessuna parte, e la scheda Rete durante una conversione mostra il lettore arrivare e nulla partire.

Quella distinzione conta per questo formato più che per la maggior parte, perché Parquet è un artefatto da data warehouse. I file con questa estensione sono estratti da tabelle di produzione — clienti, ordini, eventi, stipendi — e arrivano tramite un team dati che dovrebbe segnalare un caricamento. Qui non c'è nulla da segnalare.