사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/duckdb/duckdb-skills --skill spatial시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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_2DCSV with lat/lng needs conversion — ST_Point(longitude, latitude) (longitude first). This is the most common gotcha.
Run the query in a single bash call:
duckdb -c "
LOAD spatial;
<ADDITIONAL_SETUP>
<YOUR_QUERY>
"Step 3 — Present results
- For tabular results: show the data directly
- For spatial results: consider exporting to GeoJSON for visualization (
COPY TO 'result.geojson' WITH (FORMAT GDAL, DRIVER 'GeoJSON')) - For distance/area results: use human-readable units (km for large distances, m for small)
- For density/hotspot results: describe the pattern and offer to export for visualization
If the query fails:
- `duckdb: command not found` → delegate to
/duckdb-skills:install-duckdb - Missing extension →
INSTALL spatial; LOAD spatial;orINSTALL h3 FROM community; LOAD h3; - S3 access denied → suggest checking AWS credentials
- No results with Overture → widen the bbox, check the category spelling, or try a broader search
