Query geospatial databases and render validation maps
GeoSQL runs a map-in-the-loop agent workflow for spatial SQL on PostGIS, BigQuery, Snowflake, and Wherobots, catching geometry errors visually.
1.0.0Add to Favorites
Why it matters
Data scientists and analysts hire GeoSQL to write, validate, and execute spatial SQL queries against PostGIS, BigQuery, Snowflake, and Wherobots warehouses, with map-in-the-loop feedback that catches geometry errors text-only validation misses.
Outcomes
What it gets done
Discover warehouse schemas and write spatial SQL with correct engine-specific functions (ST_INTERSECTS, H3, bbox pruning)
Dry-run BigQuery queries to enforce cost caps and rewrite over-budget queries with tighter filters
Validate geometry by computing area/length sanity checks against domain knowledge
Render result maps through Dekart, visually inspect for errors, and self-correct geometry mistakes
Install
Add it to your toolbox
Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/dekart-xyz-geosql | bash After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.
Reports
Agent outcome reports
No reports yet
Overview
GeoSQL is a skill that runs a map-in-the-loop agent workflow for spatial SQL on PostGIS, BigQuery, Snowflake, and Wherobots. It discovers warehouse metadata, writes spatial SQL, checks query cost, validates geometry, and renders a map to catch mistakes a text-only loop would miss. Reach for it on spatial analysis tasks - site selection, accessibility, infrastructure density - where correct spatial SQL and visual geometry validation matter more than a quick unchecked query.
What it does
GeoSQL is a skill for Claude Code, Codex, GitHub Copilot, OpenCode, and Mistral Vibe that gives data scientists and analysts an agent loop for geospatial data on PostGIS, BigQuery, Snowflake, and Wherobots - no SaaS account needed, runs entirely locally or self-hosted. It runs a five-step loop: discovery (explores warehouse metadata - tables, columns, types - instead of guessing schemas, working with Overture Maps shares on BigQuery/Snowflake and private tables on PostGIS/BigQuery/Snowflake/Wherobots), SQL generation (writes spatial SQL using the right functions for the engine - ST_INTERSECTS, ST_DISTANCE, H3, bbox overlap for partition pruning), cost check (on BigQuery, every query is dry-run first to estimate bytes scanned, with a 10 GiB billing cap enforced by default - over-budget queries get rewritten cheaper rather than executed), geometry validation (computes total area or length as a sanity check against domain knowledge), and map feedback (when available, renders the result through Dekart and looks at the rendered image to correct geometry mistakes a text-only loop would miss - this step is what produces the benchmarked 4x improvement).
The included eval suite (evals/) asserts specific behaviors - cost guardrails, validation steps, correct results - not just whether the agent answered. Current results: 3 cases, 8 total assertions, 100% pass rate, averaging 3,085 tokens and 72 seconds per turn. The 4x chart compares the same tasks with and without the map-in-loop step; without maps, the agent's text-only validation misses geometry-class errors like mistaking a neighborhood polygon for a metro-area perimeter, double-counting overlapping features, or picking the wrong join key on coordinate-reference systems.
When to use - and when NOT to
Use it for spatial analysis tasks - real estate accessibility, site selection based on POI co-location and competitor distance, EV charging infrastructure density along roads - where you want the agent to write correct spatial SQL against your actual warehouse schema and catch geometry mistakes visually rather than trusting the SQL output blindly. It uses your local CLI authentication (bq, snow, dekart), so warehouse credentials never reach the agent itself.
The map-feedback step (the source of the 4x improvement) only runs when Dekart is available; the installer checks whether the optional Dekart CLI is ready and only prompts to install or initialize it when needed. On BigQuery, cost protection is opinionated by default (10 GiB billing cap, dry-run before execution) - queries that would exceed budget get rewritten rather than run, which trades completeness for cost control.
Inputs and outputs
Input is a natural-language geospatial request via /geosql (for example "Show EV charger density along major roads and render a map"); output is generated spatial SQL, query results, a rendered map (via Dekart, when available), and a geometry sanity check (total area or length) cross-checked against domain knowledge.
Integrations
pip install geosql && geosql
The interactive installer detects your agent, installs the skill, and only then checks and optionally installs the Dekart CLI, showing exact commands and a recommended default. Upgrade with pip install --upgrade geosql (and pip install --upgrade dekart if using Dekart CLI), then rerun geosql to refresh the copied skill and references. GeoSQL sends a best-effort version check with the package version and an opaque, shared installation ID stored at ${XDG_CONFIG_HOME:-~/.config}/dekart/installation_id; set DO_NOT_TRACK=1 (or DNT=1) to disable it before an ID is created, or delete the file to reset it.
Who it's for
Data scientists and analysts running geospatial queries against PostGIS, BigQuery, Snowflake, or Wherobots who want an AI agent to write correct spatial SQL and catch geometry errors visually instead of trusting unchecked SQL output.
Source README
GeoSQL
Claude Code, Codex, GitHub Copilot, OpenCode, and Mistral Vibe skill for data scientists and analysts working with geospatial data on PostGIS, BigQuery, Snowflake, and Wherobots.
Note: No SaaS account needed. Works 100% locally or self-hosted.
4x improvement on geospatial tasks with map in the loop.
Quick Start
With Python (interactive mode):
pip install geosql && geosql
GeoSQL first installs the skill into your detected agent. It then checks whether the optional Dekart CLI is ready and, only when needed, asks before installing or initializing it. The prompt shows the exact commands and defaults to the recommended install option.
After installing, prompt your agent like this:
/geosql Show EV charger density along major roads and render a map
How to update
Upgrade GeoSQL in the Python environment where it is installed:
pip install --upgrade geosql
If you use the optional Dekart CLI, update it too:
pip install --upgrade dekart
Then rerun the installer so the latest GeoSQL skill and references are copied to your detected agent:
geosql
Version telemetry
GeoSQL sends a best-effort version check with its package version and an opaque random installation ID. GeoSQL and Dekart CLI share the ID at ${XDG_CONFIG_HOME:-~/.config}/dekart/installation_id; deleting that file resets it. Set DO_NOT_TRACK=1 (or DNT=1) to disable the version check before an ID is created. CI sends a reserved non-persisted test ID.
Example prompts to try in your agent:
Real estate analysis:
/geosql Show buildings with low school accessibility in Ottawa, render as a map
Site selection:
/geosql Find the top 10 locations for Sporting Goods Store in Seattle based on POI co-location and distance to the nearest competitor. Create a map.
EV charging infrastructure:
/geosql create map EV charger density along major Romanian roads, highlighting how many charging stations are within 5 km of each motorway, trunk, or primary road segment.
How it works
GeoSQL runs an agent loop with a map in it.
- Discovery. The skill explores your warehouse metadata (tables, columns, types) instead of guessing schemas. Works with Overture Maps shares on BigQuery and Snowflake, and your private tables on PostGIS, BigQuery, Snowflake, or Wherobots.
- SQL. The agent writes spatial SQL using the right functions for your engine (
ST_INTERSECTS,ST_DISTANCE, H3, bbox overlap for partition pruning, and so on). - Cost check. On BigQuery, every query is dry-run first to estimate bytes scanned. A 10 GiB billing cap is enforced by default. Over-budget queries get rewritten cheaper (tighter bbox, lower H3 resolution, more filters) instead of executed.
- Geometry validation. The agent computes total area (polygons) or total length (lines) as a sanity check, and cross-checks against domain knowledge.
- Map feedback. When available, the agent renders the result through Dekart, looks at the rendered image, and corrects geometry mistakes the text-only loop would miss. This is the loop that gets the 4x improvement.
The skill uses your local CLI authentication (bq, snow, dekart), so warehouse credentials never go to the agent.
Benchmarks
GeoSQL ships with a reproducible eval suite under evals/. Each case asserts specific behaviors (cost guardrails, validation steps, correct result), not just "did the agent answer."
Current results on the included suite:
| Case | Assertions | Pass rate |
|---|---|---|
london-boroughs |
4 | 100% |
berlin-create-map |
3 | 100% |
paris-boundaries |
1 | 100% |
| Total | 8 | 100% |
Average: 3,085 tokens per turn, 72 s duration per turn.
The 4x improvement chart above compares the same task set with and without the map-in-loop step. Without maps, the agent's text-only validation misses geometry-class errors (mistaking a neighborhood polygon for a metro-area perimeter, double-counting overlapping features, picking the wrong join key on coordinate-reference systems). Adding the rendered map as a tool call lets the agent see those mistakes and self-correct.
Run the suite yourself:
python evals/run.py
See evals/RUNBOOK.md for setup and how to add new cases. PRs with new evals welcome.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.