The Complete Production SOP: How to Deploy and Run DuckDB Spatial Extension for GeoParquet in Autonomous AI Agents
Production SOP to install and execute DuckDB Spatial for GeoParquet across Codex, Claude Code, and Cursor. Run vector GIS analytics without PostGIS.
Technical Overview & Architectural Context
Autonomous coding agents frequently stumble when executing geospatial analytics and GIS transformations. When asked to process vector datasets like GeoParquet, Shapefiles, or GeoJSON, agents commonly default to heavy external orchestrations such as spinning up Dockerized PostGIS instances, attempting unindexed GeoPandas loops in Python, or misapplying spatial coordinate reference systems (CRS) by assuming planar calculations on EPSG:4326 lat/long coordinates. These missteps lead to multi-minute timeouts, severe context window exhaustion from tabular dumps, and corrupted spatial joins. The DuckDB Spatial Extension for GeoParquet (duckdb-spatial-geoparquet-ext) skill equips autonomous agents with deterministic boundaries. It forces the agent to resolve spatial operations inside vectorized in-memory or embedded DuckDB pipelines using native functions like ST_Point, ST_Intersects, ST_DWithin, and ST_Transform. By binding execution to predefined SQL patterns and GDAL-backed virtual tables, the skill prevents heavy dependency sprawl and enforces strict workspace-confined execution.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent runtime's global or project-level skill registry.
Autonomous runtimes like Claude Code, Codex, and Cursor scan specific skill directories to register available SOPs and trigger words. Mount this skill into `~/.agents/skills/duckdb-spatial-geoparquet-ext` (or `.claude/skills/` / `.cursor/skills/`) so the agent automatically loads spatial execution constraints whenever GIS or GeoParquet intents are detected.
mkdir -p ~/.agents/skills/duckdb-spatial-geoparquet-ext && cat << 'EOF' > ~/.agents/skills/duckdb-spatial-geoparquet-ext/SKILL.md
---
name: "duckdb-spatial-geoparquet-ext"
description: "Perform spatial GIS queries and geometry analytics at extreme speed with DuckDB Spatial."
metadata:
author: "DuckDB"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run spatial query duckdb"
- "query geoparquet duckdb"
- "calculate distance st_dwithin duckdb"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# DuckDB Spatial Extension for GeoParquet
Executes spatial SQL queries using DuckDB spatial extension: ST_Point, ST_Intersects, ST_DWithin, reading GeoParquet, Shapefiles, and GeoJSON with GDAL drivers without installing heavy PostGIS.
## Execution SOP & Rules
1. Always verify or load spatial extension: INSTALL spatial; LOAD spatial;
2. Read GeoParquet directly via standard parquet scan or ST_Read for complex drivers.
3. Validate CRS: EPSG:4326 geometries must be transformed via ST_Transform to planar projections (e.g. EPSG:3857 or local UTM) before evaluating distance in meters with ST_DWithin.
4. Project only bounding boxes or required attributes; avoid SELECT * on large geometry columns.
EOF---
name: "duckdb-spatial-geoparquet-ext"
description: "Perform spatial GIS queries and geometry analytics at extreme speed with DuckDB Spatial."
metadata:
author: "DuckDB"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run spatial query duckdb"
- "query geoparquet duckdb"
- "calculate distance st_dwithin duckdb"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Instruct the agent to use `SELECT ST_AsGeoJSON(geom)` only for sample record validation and limit row outputs to 5 rows to preserve LLM token context.
DuckDB extensions are architecture-specific. If your workspace runs inside an isolated container with `net_access: false`, ensure the spatial extension binary is pre-cached or installed during image build.
Extension Pre-compilation & Runtime Validation
Ensure the target runtime environment contains the pre-installed spatial extension binary.
Because this skill operates under `net_access: false` for strict sandbox security (98/100 score), the agent cannot run network downloads at execution time. Pre-install the extension locally using DuckDB CLI or your project's bootstrapping script so `LOAD spatial;` succeeds instantly.
python3 -c "import duckdb; con = duckdb.connect(); con.execute('INSTALL spatial; LOAD spatial;'); print('DuckDB Spatial successfully loaded')"In CI/CD or ephemeral agent sandboxes, specify `DUCKDB_EXTENSION_DIRECTORY` to share pre-downloaded extension caches across executions.
Running `INSTALL spatial;` inside a strict airgapped agent session will fail with a socket error if network access has been disabled in the agent policy.
Intent Matching & Trigger Invocation
Prompt the agent using unambiguous trigger phrases matching the SKILL.md definition.
Agent planners match user prompts against the registered trigger list (`run spatial query duckdb`, `query geoparquet duckdb`, `calculate distance st_dwithin duckdb`). Formulate requests with explicit spatial references so the planner activates this specific SOP instead of invoking general-purpose Python scripts.
Explicitly mention input GeoParquet file paths and desired target CRS (e.g., EPSG:3857) directly in the prompt to bypass redundant query iterations.
Avoid vague terms like 'find nearby places' without referencing spatial coordinates or distance thresholds; ambiguous prompts may cause the agent to attempt external Geocoding APIs.
Verification, Linting & Output Quality Gate
Enforce deterministic verification gates on the agent's generated SQL queries.
The skill instructs the agent to run local syntax checks and output validation before marking tasks complete. Ensure the agent verifies query execution against test data or runs `EXPLAIN` to guarantee spatial index usage.
duckdb -c "LOAD spatial; EXPLAIN SELECT * FROM read_parquet('data/stores.parquet') WHERE ST_DWithin(ST_Point(lon, lat), ST_Point(-73.9851, 40.7488), 0.01);"Always require the agent to run an `EXPLAIN` plan to confirm that bounding box filters (BBOX) are pushed down to the Parquet reader layer.
Do not allow the agent to commit intermediate uncompressed `.parquet` or `.geojson` artifacts exceeding workspace storage thresholds.
Real-World Scenario: Radius Filtering and Spatial Join on 1M+ Points from GeoParquet
“We have an open-source GeoParquet file at `data/poi.parquet` containing nationwide Points of Interest with columns `id`, `name`, `geometry`. Write a script that loads the DuckDB spatial extension and executes a query to find all POIs within 5,000 meters of Times Square (-73.985130, 40.748817). Export results to `output/nearby_poi.parquet`.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent attempted `LOAD spatial;` inside an environment where the extension was neither installed nor pre-cached, and `net_access: false` prevented dynamic downloading.
duckdb -c "INSTALL spatial;" && duckdb -c "LOAD spatial; SELECT ST_Point(0,0);"Root Cause: The spatial extension was not initialized in the active DuckDB connection before running spatial operators, or input geometry columns were read as raw BLOBs instead of typed geometries.
SELECT ST_DWithin(ST_GeomFromWKB(geometry), ST_Point(-73.98, 40.74), 0.05) FROM read_parquet('data/points.parquet');Frequently Asked Questions (DuckDB Spatial Extension for GeoParquet SOP)
Q:Can I use DuckDB Spatial Extension for GeoParquet across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill adheres to the universal SKILL.md specification. By placing it in `~/.agents/skills/` or your workspace root, any compliant runtime (Codex Desktop, Claude Code CLI, Cursor, Windsurf) can parse the triggers, permissions, and execution rules.
Q:How does DuckDB Spatial Extension for GeoParquet prevent context window overflow during long agent sessions?
Standard agents often dump entire spatial feature collections into chat context when testing queries. This skill instructs the agent to run headless aggregations (`COUNT(*)`, `ST_Extent()`) or limit queries to 5 rows with bounded GeoJSON representations, preserving LLM context tokens.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a 98/100 security score. It requires only workspace-scoped filesystem write permissions (`fs_write: workspace`) and requires no shell escalation (`shell_exec: false`) or network outbound calls (`net_access: false`).
Ready to equip your autonomous agent with DuckDB Spatial Extension for GeoParquet?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.