Che cos’è un file Parquet?

Parquet è un formato binario, che ha senso solo per un programma che lo conosce. Si usa per l'archiviazione e spostare dati fra programmi.

L’estensione è .parquet e il nome per esteso è Apache Parquet. Contano entrambi meno di ciò che il file può contenere, ed è di questo che parla il resto della pagina.

Apache Software Foundation lo ha pubblicato nel 2013.

L’età serve saperla per un motivo pratico: più un formato è vecchio, più programmi hanno avuto tempo di impararlo.

È pubblicata per intero, quindi la si può implementare partendo dal documento invece che per osservazione: è per questo che il formato compare in così tanti programmi, ed è per questo che file scritti vent’anni fa si aprono ancora. Una specifica pubblicata però non è la stessa cosa di una esente da royalty: dove un formato incapsula un codec, le licenze sui brevetti restano una questione a parte che lo standard non risolve.

Parquet conserva il suo contenuto esattamente. Risalvarlo non cambia nulla, quindi puoi aprirlo, modificarlo e risalvarlo quante volte vuoi senza accumulare danni: è questo che ne fa un formato di lavoro e non di consegna.

Parquet porta con sé un codice di controllo, così un file danneggiato viene rilevato invece che letto male in silenzio e una cifratura opzionale.

Un file cifrato va sbloccato prima che qualcosa possa convertirlo, qui come altrove. Una password non è qualcosa che un convertitore possa aggirare, e a uno che sostenesse il contrario non converrebbe affidare il file.

pandas, Apache Spark e DuckDB lo leggono, e così fanno quasi tutti i programmi dello stesso tipo.

Quando un file non si apre, il formato è raramente il problema: più spesso è il programma a essere più vecchio di lui. Convertire in qualcosa di più vecchio è la via d’uscita affidabile, ed è a questo che serve il resto di questo sito.

Nessun browser lo legge.

È di gran lunga il motivo più comune per convertirlo: non che il formato sia scadente, ma che il posto in cui vuoi mostrare il file non sappia leggerlo.

Parquet è pensato per essere consegnato, non per lavorarci dentro. Modificarne uno è possibile e raramente piacevole; la strada sensata passa dall’originale e da una nuova esportazione.

Le lamentele ricorrenti: fuori dal suo terreno il supporto è discontinuo.

Nessuna di queste è un motivo per evitare il formato. Sono le cose che conviene conoscere prima che una di loro ti sorprenda, che è un’affermazione diversa e più utile.

Un CSV scrive un record alla volta: nome, data, paese, importo, e poi il record successivo. Il Parquet scrive una colonna alla volta: tutti i nomi insieme, poi tutte le date, poi tutti i paesi.

Questo riordino è tutto il formato. Suona da mania archivistica, e cambia l’economia di tutto ciò che segue, perché una query che serve due colonne su cinquanta legge esattamente quelle due e salta il resto, e perché una colonna di valori simili si comprime molto meglio di una riga di valori senza relazione fra loro.

I valori di una colonna si somigliano: le date hanno la forma di una data, i codici provincia si ripetono, gli importi condividono ordine di grandezza. Da questa somiglianza vive la compressione. Inoltre il Parquet codifica prima di comprimere: una colonna con pochi valori distinti diventa un dizionario e una lista di interi piccoli, e una sequenza di valori identici diventa un conteggio.

Il risultato normale è da cinque a dieci volte più piccolo degli stessi dati in CSV, e considerevolmente di più su tabelle larghe con colonne ripetitive. Questo risparmia spazio e, soprattutto, risparmia tempo di trasferimento a tutto ciò che deve leggerlo.

Un CSV non ha tipi, quindi ogni programma che lo apre indovina, ed è lì che spariscono gli zeri iniziali e dove un codice articolo diventa una data. Il Parquet dichiara nel proprio schema il tipo di ciascuna colonna: questo è un intero a 64 bit, questa una stringa, questa una data-ora con fuso orario, questo un decimale con tante cifre.

I dati arrivano volendo dire ciò che volevano dire. Non si inferisce nulla, non dipende dalle impostazioni regionali di nessuno, e una colonna di codici postali resta una colonna di codici postali all’arrivo. Per qualsiasi cosa che si muova fra sistemi, questo conta più della compressione nella pratica.

Il file è organizzato in gruppi di righe, e ogni gruppo salva statistiche per colonna: minimo, massimo e quanti nulli ci sono. Una query che filtra per un intervallo di date legge quelle statistiche, vede che un intero gruppo esce dall’intervallo e lo salta senza decomprimere nulla.

Da qui deriva che una query su un dataset grande in Parquet può essere incomparabilmente più veloce della stessa su CSV, oltre a leggere meno colonne. E da qui anche perché partizionare per data in cartelle — una per giorno — funziona così bene: il motore scarta interi file prima di iniziare a leggere.

Nel restituire un singolo record. Ricostruire una riga costringe a raccogliere un valore da ogni colonna, esattamente il pattern di accesso per cui la disposizione non è pensata. Il Parquet è un formato analitico, non un database.

Nell’aggiungere dati. Il file viene scritto per intero, con le sue statistiche e il suo footer calcolati alla fine, quindi aggiungere una riga significa riscriverlo o scrivere un altro file. Ecco perché i flussi continui finiscono per lasciare molti file piccoli che qualcuno compatta dopo. E nel farsi guardare: è binario, un editor di testo non mostra nulla di utile e serve uno strumento per sbirciarci dentro.

La barriera è più bassa di prima. DuckDB legge un Parquet direttamente con una sola query SQL e si installa in pochi secondi. Python con pandas o Polars lo apre in una riga. Esistono diversi visualizzatori desktop gratuiti che lo mostrano come un foglio di calcolo.

L’altra via è convertirlo in CSV, ed è quella corretta quando chi ne ha bisogno lo aprirà in un foglio di calcolo, sapendo che i tipi tornano a essere congetture e che il file si moltiplica di dimensione. Conservate il Parquet come origine e generate il CSV per chi lo ha richiesto.

Dove si analizzano dati su una certa scala: data lake su storage cloud, Spark e Databricks, esportazioni da Snowflake o BigQuery, Athena, pipeline dbt, e sempre più in analisi comune con Python, dove ha silenziosamente sostituito il CSV come modo di salvare un dataframe.

È anche il formato in cui amministrazioni e progetti di ricerca iniziano a pubblicare dataset grandi, proprio perché l’alternativa — un CSV da due gigabyte che nessun foglio di calcolo apre — non serve a nessuno. Se ve ne hanno passato uno, quasi certamente viene da lì.

Vale la pena sapere cosa arriva dall’altra parte. Un intero a 64 bit viene consegnato come numero, ma se supera 2^53 viene consegnato come testo, perché oltre quel punto un numero JavaScript non lo rappresenta più con esattezza. Le date diventano stringhe in formato ISO, i campi binari esadecimale minuscolo, e qualsiasi struttura annidata testo JSON.

Nulla di questo è un difetto: è l’unico modo onesto di inserire uno schema tipizzato in una tabella piatta. Ma significa che il valore in uscita assomiglia a quello in entrata senza esserne dello stesso tipo, e vale la pena dirlo prima che qualcuno lo scopra in un confronto che non torna.

Lo scrittore guarda ogni colonna e sceglie fra quattro tipi fisici: booleano, intero a 32 bit, doppio o stringa. Un solo valore non numerico trasforma l’intera colonna in testo, e gli interi che non stanno in 32 bit passano a doppio invece che a intero a 64 bit, perché scriverli come intero a 64 prometterebbe un’esattezza che non hanno più.

Due conseguenze. Primo: i dati annidati vengono appiattiti in colonne con il nome separato da punti, come verso CSV o XLSX, quindi la struttura ad albero non arriva. Secondo: un andata e ritorno verso Parquet non restituisce lo schema originale. Se dovete conservare i tipi esatti del file di partenza, la conversione non è la strada: il Parquet originale lo è.