Query GeoParquet Files with SQL in Your Browser

Query GeoParquet Files with SQL in Your Browser

GeoParquet turns a map dataset into a Parquet file you can filter before opening GIS software. The SQL Workbench reads GeoParquet files through DuckDB's native Parquet reader. Geometry arrives as Well-Known Binary in a standard column. Every non-geometry attribute is fully queryable with SQL.

What makes GeoParquet different from regular Parquet

GeoParquet is a Parquet file with an additional metadata convention in the file-level key-value metadata. That convention records which column contains geometry, what geometry type it holds (Point, Polygon, LineString, and so on), and what coordinate reference system the coordinates use.¹ GeoParquet stores geometry as a standard Parquet BYTE_ARRAY column, encoded as Well-Known Binary.¹ Because geometry is just another column type, GeoParquet files load through the same DuckDB Parquet reader as any other .parquet file.² The additional metadata is readable but requires a spatial extension to act on geometry values. DuckDB-Wasm loads extensions only when asked, and the spatial extension is not listed among the officially available DuckDB-Wasm extensions in the current browser extension list.³ Without that extension, the geometry column contains raw binary bytes.⁴

How the workbench loads GeoParquet files

Drop a .parquet GeoParquet file and the workbench registers it as a DuckDB view. DESCRIBE returns the full schema: you see all attribute columns (VARCHAR, INTEGER, DOUBLE, DATE) alongside the geometry column, which appears as BLOB or BYTEA.⁵ The file name sets the view name, so a file named places.parquet becomes the view places, ready for immediate querying without any additional configuration.

Attribute queries without spatial SQL

You cannot run spatial predicates like ST_Intersects or ST_Within without a spatial extension, and DuckDB-WASM in the browser does not load the spatial extension automatically.³ You can, however, query all non-geometry attributes freely: SELECT fid, name, population FROM places WHERE country = 'US' works exactly as it does on any Parquet file. You can select and export the geometry column, but it appears as raw binary in CSV or JSON exports. For most attribute-only analysis, you can simply omit the geometry column from your SELECT and work with clean tabular data.

Sorting and ranking also work on attribute columns, so you can produce leaderboards like the highest-population places per country with a window function over PARTITION BY country_code ORDER BY population DESC. Because the geometry column is just bytes, including it in a wide SELECT only adds bulk to the result; leaving it out keeps the result small and readable when all you need is the tabular answer.

Useful patterns for GeoParquet attribute queries

GeoParquet files from Overture Maps, Natural Earth, or GeoPandas exports typically contain rich attribute tables alongside geometry. Inspect what attributes are available with DESCRIBE, then aggregate, filter, or join on those attributes. To find the ten most populous cities in a GeoParquet dataset: SELECT name, population FROM places ORDER BY population DESC LIMIT 10. To count features by country code: SELECT country_code, COUNT(*) FROM places GROUP BY country_code ORDER BY COUNT(*) DESC.

Preparing a filtered export for GIS

Export filtered subsets to Parquet to load into a GIS tool or Python GeoPandas for spatial analysis. The WKB geometry column carries through the Parquet export, so a downstream tool with spatial support can reconstruct the geometry from your filtered export.⁶ Before exporting, run a quick attribute summary with GROUP BY or COUNT DISTINCT to verify that your WHERE clause captured the expected feature count, and exclude the geometry column if you only need the tabular attributes.

Filtering GeoParquet attributes for downstream GIS workflows

When your GIS workflow requires a filtered subset of a large GeoParquet dataset, the workbench lets you produce that subset without installing QGIS or running a local DuckDB instance. Apply a WHERE clause on attribute columns, include the geometry column in your SELECT, then export as Parquet. The geometry column carries through the Parquet export as intact WKB bytes; a GIS tool or GeoPandas session can read the filtered export as a valid GeoParquet file.⁶

Filtering Overture Maps places to a single country

For an Overture Maps places file, SELECT * FROM places WHERE country_code = 'DE' produces a GeoParquet file containing only German features with geometry intact. The workbench handles the attribute filtering; the spatial predicate logic happens downstream in the tool that understands WKB geometry. For the full workflow: load the file, filter GeoParquet by country code, click Export, choose Parquet, then load the downloaded file in QGIS or GeoPandas for rendering and spatial analysis.

GeoParquet data sources and how to access them

Among the most useful public GeoParquet datasets is Overture Maps, which publishes open map data as GeoParquet partitioned by theme and region.⁷ The places theme contains points of interest with attributes like name, country_code, website_url, and categories alongside geometry.⁸ The buildings theme contains building footprints with height and class attributes.⁷ Downloading a single theme file from the Overture Maps release gives you a GeoParquet file you can drop directly into the workbench.

GeoPandas exports from Python produce GeoParquet via gdf.to_parquet('output.parquet') since GeoPandas 0.10 with pyarrow installed.⁹ QGIS 3.38 and later can export any vector layer to GeoParquet from the Save Vector Layer dialog when the installation includes GDAL 3.8 or higher.¹⁰ PostGIS tables are not directly exportable to GeoParquet without additional tooling; the standard approach is to export to GeoJSON first and convert with ogr2ogr, or to use DuckDB with the spatial extension on a desktop installation.¹¹

When to use this

Use this when you have a GeoParquet file from Overture Maps, GeoPandas, QGIS, or PostGIS and want to filter, aggregate, or inspect attribute data before doing spatial analysis in a GIS tool. Drop the file into the workbench and leave the geometry column out of your SELECT list when you only need the tabular attributes; DuckDB still reads the schema instantly either way.

Examples

DESCRIBE places;

SELECT country_code, COUNT(*) AS n
FROM places
WHERE feature_type = 'city'
GROUP BY country_code
ORDER BY n DESC
LIMIT 20;

SELECT *
FROM places
WHERE country_code = 'DE'
  AND population > 100000;

SELECT subtype,
       COUNT(*) AS n,
       AVG(population) AS avg_pop
FROM places
GROUP BY subtype
ORDER BY n DESC;