Perché convertire GeoJSON in GeoParquet
GeoJSON è facile da leggere e da scrivere a mano, ed è esattamente per questo che è diventato il formato predefinito per condividere dati geografici sul web. Ma questa stessa semplicità ha un costo quando un dataset supera qualche migliaio di elementi. GeoJSON memorizza ogni coordinata come testo semplice dentro una struttura JSON, e un lettore deve analizzare l'intero file, parentesi graffa dopo parentesi graffa, prima di poter guardare anche una sola proprietà. Non c'è modo di leggere solo le colonne che servono, né di conoscere l'estensione di un file senza aprirlo e scandagliarlo tutto.
GeoParquet risolve questo problema prendendo in prestito la memorizzazione a colonne che i data engineer usano già per grandi dataset tabulari. Ogni proprietà diventa una colonna a sé, la geometria diventa una colonna binaria di valori WKB, e il file porta con sé un piccolo blocco di metadati che dichiara i tipi di geometria e il bounding box complessivo fin da subito. Uno strumento come DuckDB o GeoPandas può quindi leggere solo le colonne di cui una query ha davvero bisogno, saltare i file il cui bounding box non si sovrappone a un'area di interesse, e affidarsi alla compressione integrata di Parquet per ridurre valori ripetuti come nomi di località o codici di stato.
Questo strumento esiste per eliminare l'attrito di quel primo passo. Invece di installare GDAL, un ambiente Python o uno strumento a riga di comando, puoi trascinare un file GeoJSON nel tuo browser e ottenere in pochi secondi un file GeoParquet funzionante. La conversione avviene lato client usando WebAssembly, quindi lo strumento funziona allo stesso modo sia che il file abbia dieci elementi sia che ne abbia centomila, e i tuoi dati non vengono mai inviati da nessuna parte.
GeoParquet: storia, struttura e fatti
GeoParquet è costruito sopra Apache Parquet, un formato di file orientato alle colonne che Twitter e Cloudera hanno rilasciato come progetto open source nel 2013 per l'elaborazione di dati su larga scala su Hadoop. Parquet di per sé non sa cosa sia una coordinata; si limita a memorizzare colonne tipizzate in modo efficiente, con compressione per colonna e metadati che permettono a un lettore di saltare interi blocchi di dati di cui non ha bisogno.
La specifica GeoParquet aggiunge regole geospaziali sopra quel formato generico. È stata sviluppata da una comunità aperta che lavora sotto il Cloud-Native Geospatial Forum, con la prima versione 1.0.0 pubblicata nell'agosto 2023. La versione 1.1.0, rilasciata nel 2024, ha aggiunto il supporto opzionale per una colonna con bounding box per ogni riga e un campo "covering", entrambi pensati per permettere a un lettore di filtrare le righe senza decodificare ogni geometria.
Alcuni fatti utili da sapere: GeoParquet memorizza la geometria come WKB per impostazione predefinita, quindi qualsiasi linguaggio dotato di una libreria WKB può leggere la colonna di geometria anche senza strumenti specifici per GeoParquet. La specifica assume l'ordine longitudine/latitudine in OGC:CRS84 a meno che un file non dichiari un altro sistema di riferimento di coordinate usando PROJJSON. E GeoParquet è già stato adottato ben oltre gli esperimenti: Overture Maps, il progetto cartografico congiunto sostenuto da Amazon, Meta, Microsoft e TomTom, pubblica l'intero dataset globale, edifici, luoghi, strade e confini amministrativi, come GeoParquet, e Source Cooperative ospita decine di dataset GeoParquet pubblici interrogabili direttamente dallo storage cloud.
In breve, GeoParquet non è un nuovo modello di geometria. È un accordo su come inserire una codifica di geometria già esistente e ben compresa dentro un formato di file colonnare veloce, sul quale il resto del mondo dell'ingegneria dei dati fa già affidamento.
Guida passo passo
Scegli un file .geojson dal tuo computer, incolla direttamente il testo GeoJSON nella casella, oppure fai clic su "Try sample" per caricare un piccolo file già pronto con città tedesche.
Una volta caricato il tuo GeoJSON, fai clic su "Convert to GeoParquet". La conversione avviene interamente nel tuo browser e termina in una frazione di secondo per i file tipici.
Appare un riepilogo: quanti elementi sono stati convertiti, quali tipi di geometria sono stati trovati, il bounding box, le colonne delle proprietà e la dimensione del file risultante.
Gli elementi di origine vengono disegnati sulla mappa così puoi confermare che i dati giusti siano stati convertiti prima di scaricare qualsiasi cosa.
Fai clic su "Download converted.parquet" per salvare sul tuo computer il file GeoParquet finito.
Sei casi d'uso reali
Dove GeoParquet viene davvero usato, al di là del formato di file in sé.
- Pubblicare grandi dataset aperti. Progetti come Overture Maps pubblicano dataset globali di edifici e luoghi come GeoParquet perché un unico file può contenere milioni di elementi restando comunque veloce da interrogare per regione.
- Caricare dati geospaziali in un data warehouse cloud. BigQuery, Snowflake e DuckDB leggono tutti Parquet in modo nativo. Convertire prima GeoJSON in GeoParquet significa che la colonna di geometria si carica insieme al resto della tabella, senza un passaggio di importazione separato.
- Alimentare pipeline di machine learning. Le pipeline di addestramento che leggono molti file piccoli beneficiano della struttura colonnare di Parquet: un modello che ha bisogno solo delle coordinate e di una colonna etichetta può saltare ogni altra proprietà invece di analizzare un intero oggetto GeoJSON per ogni riga.
- Archiviare dataset GIS municipali e governativi. I portali di open data che oggi distribuiscono confini cittadini, zonizzazioni o dati catastali come GeoJSON possono offrire accanto una copia GeoParquet, dando agli analisti un file più piccolo e più veloce da interrogare per gli stessi identici dati.
- Catalogare impronte satellitari e di telerilevamento. Le scene e le impronte dei tile provenienti da immagini satellitari sono naturalmente tabulari: una geometria più metadati come la data di acquisizione e la copertura nuvolosa per riga, esattamente la forma per cui è pensato un formato colonnare come Parquet.
- Pre-elaborare dati per una pipeline di mappe web. I data engineer che costruiscono vector tile o backend cartografici spesso preparano prima il GeoJSON grezzo come GeoParquet, poiché strumenti a valle come DuckDB spatial o Apache Sedona possono filtrare e rimodellare milioni di elementi molto più velocemente che riparsando testo JSON.
Domande e risposte tecniche
Dieci domande comuni su come funziona questo convertitore, con risposte dirette.
1. Cos'è GeoParquet, in termini semplici?
GeoParquet è un modo per memorizzare dati geografici (punti, linee, poligoni e le informazioni ad essi associate) dentro un normale file Apache Parquet. Parquet è un formato di file basato su colonne costruito per analisi veloci. GeoParquet aggiunge solo un piccolo insieme di regole in modo che le colonne di geometria possano risiedere dentro un file Parquet e continuare a essere lette correttamente dal software GIS.
2. Come viene effettivamente memorizzata una geometria all'interno del file?
Ogni geometria è codificata come WKB, abbreviazione di Well-Known Binary. WKB è una ricetta byte per byte: un byte indica se i numeri sono little-endian o big-endian, quattro byte indicano il tipo di geometria (punto, linea, poligono e così via), e poi seguono le coordinate come numeri grezzi a 8 byte. Questo valore WKB è memorizzato in una colonna binaria del file Parquet, una riga per elemento.
3. Un singolo file GeoParquet può contenere più di un tipo di geometria?
Sì. Una singola colonna di geometria può mescolare punti, linee e poligoni, perché WKB porta con sé il proprio codice di tipo dentro ogni valore. Questo convertitore registra ogni tipo di geometria che incontra in un elenco "geometry_types" dentro i metadati del file, così un lettore sa in anticipo cosa aspettarsi senza dover scandagliare ogni riga.
4. Cos'è la chiave di metadati "geo", e perché è importante?
Ogni file GeoParquet porta con sé un piccolo oggetto JSON sotto una chiave a livello di schema chiamata "geo". Indica la colonna di geometria principale, dichiara la codifica (WKB), elenca i tipi di geometria presenti e fornisce il bounding box del file. Senza questa chiave, un file Parquet è solo una tabella di byte. Con essa, qualsiasi strumento consapevole di GeoParquet sa esattamente come trasformare quei byte di nuovo in geometrie reali.
5. Come si confronta GeoParquet con GeoJSON per dimensione del file e velocità di lettura?
GeoJSON memorizza le coordinate come testo, quindi un numero come 13.404954 occupa nove caratteri. GeoParquet memorizza lo stesso numero come un double binario a 8 byte, e poi Parquet comprime i pattern ripetuti in tutta la colonna. Su dataset reali questo produce regolarmente file da 5 a 10 volte più piccoli di GeoJSON, e poiché Parquet è basato su colonne, una query che ha bisogno solo di una colonna di proprietà può saltare del tutto la lettura della geometria.
6. Quale sistema di riferimento delle coordinate usa GeoParquet per impostazione predefinita?
A meno che un file non dichiari diversamente, un lettore GeoParquet presume che le coordinate siano longitudine e latitudine in OGC:CRS84, lo stesso ordine di coordinate e lo stesso datum del GeoJSON standard. Questo convertitore segue quella regola predefinita, poiché prende GeoJSON come input.
7. Il file memorizza un bounding box per l'intero dataset?
Sì. Questo convertitore calcola un bounding box progressivo, X e Y minimi e massimi, mentre elabora ogni elemento, e lo scrive nei metadati "geo" come bbox della colonna. Un lettore può controllare quel singolo bbox prima ancora di decidere se aprire il file, il che è utile quando si filtrano molti file per area.
8. Quale software può aprire il file .parquet prodotto da questo strumento?
Qualsiasi strumento costruito sulla specifica GeoParquet può leggerlo: DuckDB con la sua estensione spaziale, GeoPandas, Apache Sedona, QGIS (versioni recenti), e la maggior parte dei data warehouse cloud che supportano Parquet con un lettore consapevole della geometria sopra. Poiché sotto è semplice Apache Parquet, anche un lettore Parquet non spaziale può aprire il file e vedere la geometria come colonna binaria.
9. La conversione fa perdere precisione alle coordinate?
No. Le coordinate GeoJSON sono numeri JSON, che JavaScript già rappresenta internamente come float a doppia precisione IEEE-754. WKB memorizza ogni coordinata esattamente come lo stesso double IEEE-754, quindi la conversione è una ricodifica binaria diretta, non un'operazione di arrotondamento. Il ciclo completo è stato verificato byte per byte durante lo sviluppo.
10. Il mio file GeoJSON viene caricato su un server?
No. Il parsing, la codifica WKB e la scrittura di Parquet avvengono tutti dentro il tuo browser usando WebAssembly. Il tuo file non lascia mai il tuo dispositivo, e nessuna parte della conversione tocca un server.
La matematica dietro la conversione
La conversione non ha alcuna ambiguità o stima al suo interno. Ogni passaggio è un'operazione fissa e reversibile su byte e numeri, ed è proprio questo a rendere possibile un ciclo completo byte per byte.
1. Le coordinate sono già double IEEE-754
Una coordinata GeoJSON come 13.404954 viene analizzata dal parser JSON di JavaScript in un float a 64 bit a doppia precisione IEEE-754: 1 bit di segno, 11 bit di esponente e 52 bit di mantissa, dando circa 15-17 cifre decimali significative di precisione. WKB memorizza ogni coordinata esattamente come lo stesso double a 8 byte, scritto in ordine little-endian. Qui non avviene alcun arrotondamento o cambio di formato; la conversione copia gli stessi 64 bit già presenti in memoria dentro il buffer di output.
2. Struttura e dimensione dei byte in WKB
Ogni valore WKB inizia con un flag di endianness di 1 byte e un codice di tipo di geometria a 4 byte senza segno, quindi l'intestazione fissa è sempre di 5 byte. Dopodiché, la dimensione dipende dal tipo di geometria. Per un anello di n coppie di coordinate (usato da LineString e da ogni anello di un Polygon), 4 byte registrano il numero di punti e poi ogni coppia costa 16 byte (8 per X, 8 per Y):
ring_bytes(n) = 4 + 16n Point = 5 + 16 = 21 bytes LineString(n) = 5 + ring_bytes(n) Polygon(rings) = 5 + 4 + Σ ring_bytes(ring) for each ring MultiPoint(n) = 5 + 4 + 21n (each point repeats the 5-byte header) MultiLineString = 5 + 4 + Σ (5 + ring_bytes(line)) for each line MultiPolygon = 5 + 4 + Σ (5 + 4 + Σ ring_bytes(ring)) for each polygon, each ring
Questo è preciso, non approssimativo: il convertitore calcola la dimensione esatta in byte di una geometria prima di allocarne il buffer, scrive l'intestazione e ogni coordinata con un DataView, e non ridimensiona mai il buffer a metà scrittura. Una semplice linea a due punti richiede quindi esattamente 5 + 4 + 32 = 41 byte, ogni volta, su ogni piattaforma.
3. Il bounding box è un singolo passaggio lineare
Il bounding box [minX, minY, maxX, maxY] viene calcolato visitando ogni coppia di coordinate esattamente una volta e mantenendo un minimo e un massimo progressivi, una riduzione O(n) dove n è il numero totale di coppie di coordinate in tutti gli elementi. Non c'è ordinamento e non c'è un secondo passaggio: ogni nuova coordinata deve solo essere confrontata con i quattro valori progressivi, quindi il costo del calcolo del bbox cresce linearmente con la dimensione del dataset, mai più velocemente né più lentamente.
4. Perché il file finisce per essere più piccolo
Una coppia di coordinate GeoJSON come [13.404954, 52.520008] occupa circa 20 byte come testo, comprese le parentesi quadre e la virgola. La stessa coppia come due double WKB occupa esattamente 16 byte, un modesto risparmio di per sé. Il guadagno maggiore viene dalla codifica a livello di colonna di Parquet: una colonna di proprietà testuale come un nome di paese ripetuto su migliaia di righe si comprime estremamente bene con la codifica a dizionario, poiché Parquet deve memorizzare ogni stringa distinta una sola volta più un breve riferimento intero per riga. Le colonne numeriche traggono benefici simili dalle codifiche run-length e bit-packing quando i valori si ripetono o rientrano in un intervallo ristretto. Nulla di tutto ciò è disponibile in un formato testuale basato su righe come GeoJSON, dove ogni valore viene riscritto come testo su ogni singola riga.
Nel complesso, la pipeline di conversione è deterministica in ogni fase: analizza un double IEEE-754 noto, lo scrive in una struttura di byte nota, tiene traccia di un min/max progressivo e passa il risultato a un compressore colonnare generico. Questo determinismo è esattamente ciò che rende il ciclo completo senza perdite, ed è il motivo per cui lo stesso file GeoJSON convertito due volte su due macchine diverse produce un output GeoParquet identico byte per byte.
La conversione avviene interamente nel tuo browser usando Apache Arrow e una build WebAssembly di parquet-wasm. Nessun file viene mai caricato su un server. Tessere della mappa © contributori di OpenStreetMap, disegnate con Protomaps (ospitato da KONAKTIVE), con CARTO come riserva.
