DuckDB & analytic SQL
A spatial database with no server: querying GeoParquet, joining millions of rows, and where it beats a GeoDataFrame.
DuckDB is a spatial database with no server and no load step. It reads GeoParquet, GeoPackage, shapefiles and CSV in place — including over HTTP — and runs analytic SQL over them at a speed that makes a GeoDataFrame look like the wrong tool for anything joined.
What it gives up is the other half of what a database is for: no concurrent writers, no shared instance, no index it maintains between sessions. That trade is exactly right for analysis over files and exactly wrong for an application several people write to, which is the line between this topic and PostGIS.
Below: the concepts cover the spatial extension, how it reads remote files and where its CRS handling differs from GeoPandas; the how-to guides query, join and convert; and the fixes cover the reads and transforms that behave differently from what you expected.
🧭 Start with the concepts
The ideas the how-to guides below assume you already have.
- DuckDB Spatial Explained: A Spatial Database That Is Just a File
- Columnar or Row Storage: Why DuckDB Is Fast on Wide Tables
- CRS in DuckDB: Why ST_Transform Moves Your Data to the Wrong Place
- How DuckDB Uses (and Does Not Use) a Spatial Index
- DuckDB or PostGIS: Which One a Workflow Needs
- DuckDB's Memory Model: Streaming, Spilling and Limits
⚙️ Then do the task
Step-by-step walkthroughs with code you can copy and adapt.
- How to Install and Load the DuckDB Spatial Extension
- How to Read Shapefiles, GeoJSON and GeoParquet in DuckDB
- How to Run a Spatial Join in DuckDB
- How to Aggregate Millions of Points into a Grid with DuckDB
- How to Query Remote GeoParquet over HTTP with DuckDB
- How to Query Hive-Partitioned GeoParquet in DuckDB
🔧 When it breaks
The errors this topic produces, with the cause explained rather than just the command.
Learning paths through this topic
A curated route rather than a list — the guides in the order that builds on itself.
Related topics
Subjects that keep coming up alongside this one, most overlap first.