Porquê converter GeoJSON para GeoParquet
O GeoJSON é fácil de ler e de escrever à mão, e é exatamente por isso que se tornou o formato predefinido para partilhar dados de mapas na web. Mas essa mesma simplicidade tem um custo assim que um conjunto de dados cresce para além de alguns milhares de elementos. O GeoJSON guarda cada coordenada como texto simples dentro de uma estrutura JSON, e um leitor tem de analisar o ficheiro inteiro, chaveta a chaveta, antes de poder olhar sequer para uma propriedade. Não há forma de ler apenas as colunas de que precisa, nem de saber a extensão de um ficheiro sem o abrir e percorrer por completo.
O GeoParquet resolve isto ao pedir emprestado o armazenamento em colunas que os engenheiros de dados já usam para grandes conjuntos de dados tabulares. Cada propriedade torna-se a sua própria coluna, a geometria torna-se uma coluna binária de valores WKB, e o ficheiro transporta um pequeno bloco de metadados que indica logo à partida os tipos de geometria e a caixa delimitadora geral. Uma ferramenta como o DuckDB ou o GeoPandas pode então ler apenas as colunas de que uma consulta realmente precisa, ignorar ficheiros cuja caixa delimitadora não se sobrepõe a uma área de interesse, e confiar na compressão nativa do Parquet para reduzir valores repetidos, como nomes de locais ou códigos de estado.
Esta ferramenta existe para eliminar o atrito desse primeiro passo. Em vez de instalar o GDAL, um ambiente Python ou uma ferramenta de linha de comandos, pode arrastar um ficheiro GeoJSON para o seu navegador e obter em segundos um ficheiro GeoParquet funcional. A conversão é executada do lado do cliente usando WebAssembly, pelo que a ferramenta funciona da mesma forma quer o seu ficheiro tenha dez elementos quer tenha cem mil, e os seus dados nunca são enviados para lado nenhum.
GeoParquet: história, estrutura e factos
O GeoParquet é construído sobre o Apache Parquet, um formato de ficheiro orientado a colunas que o Twitter e a Cloudera lançaram como projeto de código aberto em 2013 para processamento de dados em larga escala no Hadoop. O Parquet, por si só, não tem qualquer noção do que é uma coordenada; limita-se a armazenar colunas tipadas de forma eficiente, com compressão por coluna e metadados que permitem a um leitor ignorar blocos inteiros de dados de que não precisa.
A especificação GeoParquet acrescenta regras geoespaciais sobre esse formato de uso geral. Foi desenvolvida por uma comunidade aberta que trabalha sob o Cloud-Native Geospatial Forum, com a primeira versão 1.0.0 publicada em agosto de 2023. A versão 1.1.0, lançada em 2024, acrescentou suporte opcional para uma coluna de caixa delimitadora por linha e um campo "covering", ambos destinados a permitir que um leitor filtre linhas sem descodificar cada geometria.
Alguns factos que vale a pena conhecer: o GeoParquet armazena a geometria como WKB por predefinição, pelo que qualquer linguagem com uma biblioteca WKB consegue ler a coluna de geometria mesmo sem ferramentas específicas para GeoParquet. A especificação assume a ordem longitude/latitude em OGC:CRS84, a menos que um ficheiro declare outro sistema de referência de coordenadas usando PROJJSON. E o GeoParquet já foi adotado bem para além de experiências: o Overture Maps, o projeto cartográfico conjunto apoiado pela Amazon, Meta, Microsoft e TomTom, publica todo o seu conjunto de dados global, edifícios, locais, estradas e limites administrativos, como GeoParquet, e o Source Cooperative hospeda dezenas de conjuntos de dados GeoParquet públicos que qualquer pessoa pode consultar diretamente a partir do armazenamento na nuvem.
Em resumo, o GeoParquet não é um novo modelo de geometria. É um acordo sobre como colocar uma codificação de geometria já existente e bem compreendida dentro de um formato de ficheiro colunar rápido, no qual o resto do mundo da engenharia de dados já confia.
Guia passo a passo
Escolha um ficheiro .geojson do seu computador, cole o texto GeoJSON diretamente na caixa, ou clique em "Try sample" para carregar um pequeno ficheiro já pronto com cidades alemãs.
Depois de o seu GeoJSON estar carregado, clique em "Convert to GeoParquet". A conversão é executada inteiramente no seu navegador e termina numa fração de segundo para ficheiros típicos.
Aparece um resumo: quantos elementos foram convertidos, que tipos de geometria foram encontrados, a caixa delimitadora, as colunas de propriedades e o tamanho do ficheiro resultante.
Os elementos de origem são desenhados no mapa para que possa confirmar que os dados corretos foram convertidos antes de descarregar seja o que for.
Clique em "Download converted.parquet" para guardar no seu computador o ficheiro GeoParquet terminado.
Seis casos de uso reais
Onde o GeoParquet é realmente utilizado, para além do próprio formato de ficheiro.
- Publicar grandes conjuntos de dados abertos. Projetos como o Overture Maps publicam conjuntos de dados globais de edifícios e locais como GeoParquet porque um único ficheiro pode conter milhões de elementos e continuar rápido a consultar por região.
- Carregar dados geoespaciais num data warehouse na nuvem. O BigQuery, o Snowflake e o DuckDB leem todos Parquet de forma nativa. Converter primeiro GeoJSON para GeoParquet significa que a coluna de geometria é carregada juntamente com o resto da tabela, sem um passo de importação separado.
- Alimentar pipelines de machine learning. Os pipelines de treino que leem muitos ficheiros pequenos beneficiam do esquema colunar do Parquet: um modelo que só precisa das coordenadas e de uma coluna de rótulo pode ignorar todas as outras propriedades em vez de analisar um objeto GeoJSON completo por linha.
- Arquivar conjuntos de dados GIS municipais e governamentais. Os portais de dados abertos que atualmente distribuem limites de cidades, zonamento ou dados cadastrais como GeoJSON podem oferecer também uma cópia GeoParquet, dando aos analistas um ficheiro mais pequeno e mais rápido de consultar para exatamente os mesmos dados.
- Catalogar pegadas de satélite e de deteção remota. As cenas e as pegadas de tiles de imagens de satélite são naturalmente tabulares: uma geometria mais metadados como a data de captura e a cobertura de nuvens por linha, exatamente a forma para que um formato colunar como o Parquet foi criado.
- Pré-processar dados para um pipeline de mapas na web. Os engenheiros de dados que constroem vector tiles ou back-ends de mapas frequentemente preparam primeiro o GeoJSON em bruto como GeoParquet, uma vez que ferramentas a jusante como o DuckDB spatial ou o Apache Sedona conseguem filtrar e remodelar milhões de elementos muito mais depressa do que analisar novamente texto JSON.
Perguntas e respostas técnicas
Dez perguntas comuns sobre o funcionamento deste conversor, respondidas diretamente.
1. O que é o GeoParquet, em termos simples?
O GeoParquet é uma forma de guardar dados de mapas (pontos, linhas, polígonos e as informações a eles associadas) dentro de um ficheiro Apache Parquet comum. O Parquet é um formato de ficheiro baseado em colunas, construído para análises rápidas. O GeoParquet apenas acrescenta um pequeno conjunto de regras para que as colunas de geometria possam existir dentro de um ficheiro Parquet e continuar a ser lidas corretamente por software GIS.
2. Como é que uma geometria é efetivamente guardada dentro do ficheiro?
Cada geometria é codificada como WKB, abreviatura de Well-Known Binary. O WKB é uma receita byte a byte: um byte indica se os números estão em little-endian ou big-endian, quatro bytes indicam o tipo de geometria (ponto, linha, polígono, e assim por diante), e depois seguem-se as coordenadas como números em bruto de 8 bytes. Este valor WKB é guardado numa coluna binária do ficheiro Parquet, uma linha por elemento.
3. Um único ficheiro GeoParquet pode conter mais do que um tipo de geometria?
Sim. Uma única coluna de geometria pode misturar pontos, linhas e polígonos, porque o WKB transporta o seu próprio código de tipo dentro de cada valor. Este conversor regista cada tipo de geometria que encontra numa lista "geometry_types" dentro dos metadados do ficheiro, para que um leitor saiba antecipadamente o que esperar sem ter de percorrer todas as linhas.
4. O que é a chave de metadados "geo", e porque é que é importante?
Todo o ficheiro GeoParquet transporta um pequeno objeto JSON sob uma chave ao nível do esquema chamada "geo". Indica a coluna de geometria principal, declara a codificação (WKB), lista os tipos de geometria presentes e indica a caixa delimitadora do ficheiro. Sem esta chave, um ficheiro Parquet é apenas uma tabela de bytes. Com ela, qualquer ferramenta que reconheça o GeoParquet sabe exatamente como transformar esses bytes de novo em geometrias reais.
5. Como se compara o GeoParquet ao GeoJSON em tamanho de ficheiro e velocidade de leitura?
O GeoJSON guarda as coordenadas como texto, pelo que um número como 13.404954 ocupa nove caracteres. O GeoParquet guarda o mesmo número como um double binário de 8 bytes, e depois o Parquet comprime padrões repetidos em toda a coluna. Em conjuntos de dados reais, isto produz habitualmente ficheiros de 5 a 10 vezes mais pequenos do que o GeoJSON, e como o Parquet é baseado em colunas, uma consulta que só precise de uma coluna de propriedades pode saltar por completo a leitura da geometria.
6. Que sistema de referência de coordenadas usa o GeoParquet por predefinição?
A menos que um ficheiro declare o contrário, um leitor GeoParquet assume que as coordenadas são longitude e latitude em OGC:CRS84, a mesma ordem de coordenadas e o mesmo datum do GeoJSON padrão. Este conversor segue essa predefinição, uma vez que recebe GeoJSON como entrada.
7. O ficheiro guarda uma caixa delimitadora para todo o conjunto de dados?
Sim. Este conversor calcula uma caixa delimitadora progressiva, X e Y mínimos e máximos, à medida que processa cada elemento, e escreve-a nos metadados "geo" como o bbox da coluna. Um leitor pode verificar esse único bbox antes de sequer decidir se abre o ficheiro, o que é útil ao filtrar muitos ficheiros por área.
8. Que software consegue abrir o ficheiro .parquet que esta ferramenta produz?
Qualquer ferramenta construída sobre a especificação GeoParquet consegue lê-lo: o DuckDB com a sua extensão espacial, o GeoPandas, o Apache Sedona, o QGIS (versões recentes), e a maioria dos data warehouses na nuvem que suportam Parquet com um leitor que reconhece geometria por cima. Como por baixo é simples Apache Parquet, até um leitor Parquet não espacial consegue abrir o ficheiro e ver a geometria como uma coluna binária.
9. A conversão faz perder precisão às coordenadas?
Não. As coordenadas GeoJSON são números JSON, que o JavaScript já representa internamente como floats de dupla precisão IEEE-754. O WKB guarda cada coordenada exatamente como o mesmo double IEEE-754, pelo que a conversão é uma recodificação binária direta, não uma operação de arredondamento. O ciclo completo foi verificado byte a byte durante o desenvolvimento.
10. O meu ficheiro GeoJSON é carregado para um servidor?
Não. A análise, a codificação WKB e a escrita do Parquet são todas executadas dentro do seu navegador, usando WebAssembly. O seu ficheiro nunca sai do seu dispositivo, e nenhuma parte da conversão toca num servidor.
A matemática por detrás da conversão
A conversão não tem qualquer ambiguidade ou estimativa. Cada passo é uma operação fixa e reversível sobre bytes e números, o que é precisamente o que torna possível um ciclo completo byte a byte.
1. As coordenadas já são doubles IEEE-754
Uma coordenada GeoJSON como 13.404954 é analisada pelo analisador JSON do JavaScript como um float de dupla precisão IEEE-754 de 64 bits: 1 bit de sinal, 11 bits de expoente e 52 bits de mantissa, o que dá cerca de 15 a 17 dígitos decimais significativos de precisão. O WKB guarda cada coordenada exatamente como este mesmo double de 8 bytes, escrito em ordem little-endian. Aqui não acontece qualquer arredondamento ou mudança de formato; a conversão copia os mesmos 64 bits que já estavam em memória para dentro do buffer de saída.
2. Estrutura e tamanho dos bytes em WKB
Todo o valor WKB começa com um sinalizador de endianness de 1 byte e um código de tipo de geometria de 4 bytes sem sinal, pelo que o cabeçalho fixo tem sempre 5 bytes. Depois disso, o tamanho depende do tipo de geometria. Para um anel de n pares de coordenadas (usado por LineString e por cada anel de um Polygon), 4 bytes registam o número de pontos e depois cada par custa 16 bytes (8 para X, 8 para 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
Isto é preciso, não aproximado: o conversor calcula o tamanho exato em bytes de uma geometria antes de alocar o seu buffer, escreve o cabeçalho e cada coordenada com um DataView, e nunca redimensiona o buffer a meio da escrita. Uma linha simples de dois pontos ocupa, por isso, exatamente 5 + 4 + 32 = 41 bytes, sempre, em qualquer plataforma.
3. A caixa delimitadora é uma única passagem linear
A caixa delimitadora [minX, minY, maxX, maxY] é calculada visitando cada par de coordenadas exatamente uma vez e mantendo um mínimo e um máximo progressivos, uma redução O(n) em que n é o número total de pares de coordenadas em todos os elementos. Não há ordenação nem uma segunda passagem: cada nova coordenada só precisa de ser comparada com os quatro valores progressivos, pelo que o custo de calcular o bbox cresce linearmente com o tamanho do conjunto de dados, nunca mais depressa nem mais devagar.
4. Porque é que o ficheiro acaba por ficar mais pequeno
Um par de coordenadas GeoJSON como [13.404954, 52.520008] ocupa cerca de 20 bytes como texto, incluindo parênteses retos e a vírgula. O mesmo par como dois doubles WKB ocupa exatamente 16 bytes, uma poupança modesta por si só. O ganho maior vem da codificação ao nível da coluna do Parquet: uma coluna de propriedade de texto, como um nome de país repetido em milhares de linhas, comprime-se extremamente bem com codificação por dicionário, uma vez que o Parquet só tem de guardar cada cadeia distinta uma vez, mais uma referência inteira curta por linha. As colunas numéricas beneficiam de forma semelhante das codificações run-length e bit-packing quando os valores se repetem ou se enquadram num intervalo estreito. Nada disto está disponível num formato de texto baseado em linhas como o GeoJSON, onde cada valor é reescrito como texto em cada linha individual.
No conjunto, o pipeline de conversão é determinístico em todas as fases: analisa um double IEEE-754 conhecido, escreve-o numa estrutura de bytes conhecida, mantém um mínimo/máximo progressivo, e entrega o resultado a um compressor colunar de uso geral. Este determinismo é exatamente o que torna o ciclo completo sem perdas, e é o motivo pelo qual o mesmo ficheiro GeoJSON convertido duas vezes em duas máquinas diferentes produz um resultado GeoParquet idêntico byte a byte.
A conversão é executada inteiramente no seu navegador, usando Apache Arrow e uma compilação WebAssembly do parquet-wasm. Nenhum ficheiro é alguma vez enviado para um servidor. Blocos do mapa © colaboradores do OpenStreetMap, desenhados com Protomaps (hospedado por KONAKTIVE), com CARTO como reserva.
