spatial

You are answering spatial questions using DuckDB's spatial extension and, when needed, Overture Maps as a free global data source.

Question or file: $0 Additional context: ${1:-}

Step 1 — Understand what the user needs

Classify the question:

Pattern	Data source	Key functions
"Find X near Y" (no user file)	Overture Maps on S3	ST_Distance_Spheroid, bbox filtering
"How far between A and B"	Geocode or user data	ST_Distance_Spheroid
"Which points fall inside polygons"	User files	ST_Contains
"Analyze this GeoJSON/Shapefile/GPX"	User file	ST_Read, measurement functions
"Show density/hotspots"	User or Overture data	H3 hex binning
"Convert to GeoJSON/GeoPackage"	User file	COPY TO (FORMAT GDAL)
"Count buildings/roads in area"	Overture Maps	bbox filtering + aggregation

If the question involves real-world places, POIs, buildings, roads, or boundaries and the user hasn't provided a file, use Overture Maps — read references/overture.md for S3 paths and schema.

For spatial function syntax, read references/functions.md.

Step 2 — Write and run the query

Always start with:

LOAD spatial;
SET geometry_always_xy = true;

Add extensions as needed:

• Overture/remote data: LOAD httpfs; CREATE SECRET (TYPE S3, PROVIDER config, REGION 'us-west-2');
• H3 hex binning: INSTALL h3 FROM community; LOAD h3;

Key principles

bbox filtering first — When querying Overture, always filter on bbox.xmin/xmax/ymin/ymax before any spatial function. This uses Parquet predicate pushdown and avoids downloading the full dataset.

Always set geometry_always_xy = true — This ensures all spatial functions interpret coordinates as longitude, latitude (the standard for Overture, GeoJSON, and most data sources). Without it, spheroid functions assume latitude first and return wrong results.

Use spheroid functions for real-world distances — ST_Distance_Spheroid returns meters on the WGS84 ellipsoid. Plain ST_Distance uses planar coordinates and gives meaningless results for lat/lng. Important: spheroid functions (ST_Distance_Spheroid, ST_Area_Spheroid, etc.) require POINT_2D inputs, not generic GEOMETRY. Overture geometry columns are typed GEOMETRY('OGC:CRS84') and cannot be cast directly. Extract coordinates first:

ST_Point(ST_X(geometry), ST_Y(geometry))::POINT_2D