For modern Geographic Information Systems (GIS) professionals, writing efficient spatial SQL is a core competency. However, the analytical landscape is rapidly evolving with the integration of Large Language Models (LLMs). A prime example of this evolution is the open-source project GeoSQL, specifically designed to turn AI models like Claude, Codex, and GitHub Copilot into capable geospatial analytics agents.
What is GeoSQL?
GeoSQL (maintained under the Dekart repository on GitHub) is an AI agent skill that assists data scientists and GIS analysts working with complex spatial data. Instead of merely generating text-based SQL queries, it creates an interactive loop where the AI actively queries metadata, writes database-specific spatial functions, and renders maps to visually verify its own work.
The tool is completely local or self-hosted, requiring no additional SaaS accounts to function.
The "Map-in-the-Loop" Advantage
The standout feature of GeoSQL is its visual feedback mechanism, which boasts a 4x improvement in accuracy on geospatial tasks. Standard text-based AI agents frequently make geometry-class errors, such as mistaking a local neighborhood polygon for a larger metro-area perimeter, double-counting overlapping features, or picking incorrect join keys for different coordinate reference systems.
By integrating with the Dekart CLI, the agent renders a map of its query results, "looks" at the generated image, and self-corrects geometrical mistakes that a text-only loop would completely miss.
Core Workflow and Capabilities
GeoSQL runs a sophisticated agent loop designed to handle the nuances and scale of spatial data. The process includes:
Intelligent Discovery: The agent explores your actual data warehouse metadata (including tables, columns, and data types) rather than blindly guessing schemas.
Engine-Specific SQL Generation: It writes optimized spatial SQL using the correct functions for your specific database engine, utilizing commands like
ST_INTERSECTS,ST_DISTANCE, H3 grid functions, and bounding box overlaps for partition pruning.Built-in Cost Guardrails: When querying cloud databases like BigQuery, every query is first dry-run to estimate the bytes scanned. By default, a 10 GiB billing cap is enforced. If a query exceeds the budget, the agent automatically rewrites it to be cheaper—using tighter bounding boxes, lower H3 resolutions, or additional filters—instead of executing it.
Geometry Validation: The agent runs sanity checks against domain knowledge by computing the total area of polygons or the total length of lines before finalizing the output.
Supported Platforms and Integrations
GeoSQL is built to work seamlessly with the modern spatial data stack. It connects to major data warehouses and spatial databases, including:
PostGIS
Google BigQuery
Snowflake
Wherobots
It also supports direct integration with massive open datasets, such as Overture Maps shares. Importantly, because the skill utilizes your local command-line authentication (such as bq or snow), your private warehouse credentials are never exposed directly to the AI agent.
Installation and Practical Use
Getting started requires only basic Python package management. Users can install the tool directly into their detected agent by running pip install geosql && geosql. For full setup documentation, you can visit the GeoSQL GitHub page.
Once installed, GIS professionals can prompt their AI agent with natural language commands to execute complex spatial tasks. Examples of prompts include requesting a map of EV charger density along major roads, analyzing real estate for low school accessibility, or finding prime retail locations based on point-of-interest co-location and competitor distance.
Acknowledgment
A special thanks to the creators and maintainers of GeoSQL at the Dekart repository for developing and open-sourcing this incredible tool. By bridging the gap between AI and complex spatial databases, they are pushing the boundaries of what GIS professionals can achieve and making advanced geospatial analytics more accessible than ever. Their contributions to the modern spatial data stack are deeply appreciated by the community!
