Skip to content

Quick Start

Get started with geoparquet-io in 5 minutes.

Installation

uv tool install geoparquet-io

uv add geoparquet-io

See Installation Guide for more options.

Reading and Writing

# Convert Shapefile/GeoJSON/GeoPackage to optimized GeoParquet
gpio convert input.shp output.parquet

# Inspect file structure
gpio inspect myfile.parquet
# Rows: 1,523,847 | Size: 245.3 MB | CRS: EPSG:4326

# Preview first 5 rows
gpio inspect myfile.parquet --head 5

import geoparquet_io as gpio

# Read a file
table = gpio.read('data.parquet')
table.num_rows
# 1523847

# Convert from other formats
table = gpio.convert('data.shp')
table.write('output.parquet')

Transforming Data

# Add bbox column for faster spatial queries
gpio add bbox input.parquet output.parquet

# Sort using Hilbert curve for spatial locality
gpio sort hilbert input.parquet sorted.parquet

# Chain with pipes—no intermediate files
gpio add bbox input.parquet | gpio sort hilbert - output.parquet

import geoparquet_io as gpio

# Chain operations fluently
gpio.read('input.parquet') \
    .add_bbox() \
    .sort_hilbert() \
    .write('output.parquet')

Adding Spatial Indices

gpio add s2 is unavailable in this release

S2 needs the geography DuckDB community extension, which is published only up to DuckDB 1.5.1 while gpio requires DuckDB 1.5.2 or newer, so gpio add s2 and gpio partition s2 stop with an explanation instead of running. Use gpio add a5 — a hierarchical, globally-uniform cell index over the whole sphere — until the extension is republished upstream. See S2 Spherical Cells.

# H3 hexagonal cells
gpio add h3 input.parquet output.parquet --resolution 9

# A5 pentagonal cells
gpio add a5 input.parquet output.parquet --resolution 15

# Chain multiple indices
gpio add bbox input.parquet | gpio add h3 -r 9 - | gpio sort hilbert - output.parquet

gpio.read('input.parquet') \
    .add_bbox() \
    .add_h3(resolution=9) \
    .sort_hilbert() \
    .write('output.parquet')

Partitioning

# Partition by H3 cells
gpio partition h3 input.parquet output_dir/ --resolution 6

# Preview first
gpio partition h3 input.parquet --resolution 6 --preview

gpio.read('input.parquet') \
    .add_h3(resolution=9) \
    .partition_by_h3('output/', resolution=6)

Performance: CLI vs Python

Approach Time (75MB file) Notes
CLI (file-based) 34s Each command writes intermediate file
CLI (piped) 16s Arrow IPC streaming between commands
Python API 7s In-memory, no I/O overhead

The Python API is fastest because data stays in memory. Use CLI for shell scripts and one-off commands; use Python for applications and maximum performance.

Next Steps