Why Spatial SQL Needs a Map in the LLM Loop

Writing spatial SQL is a special kind of headache. A single misplaced coordinate transformation or an unindexed spatial join can turn a simple query into a database freeze or a massive cloud bill. When developers turn to LLMs for help, the results are often worse. LLMs are notoriously bad at spatial reasoning because they are fundamentally text-based. They cannot see that a generated polygon is self-intersecting, nor can they easily spot when they have used the wrong coordinate reference system (CRS).

This is the problem that GeoSQL aims to solve. Rather than relying on an LLM to write spatial queries in a vacuum, GeoSQL introduces a multimodal feedback loop that renders maps and lets the agent inspect its own work. By combining schema discovery, strict cost guardrails, and visual validation, it moves AI-driven GIS from a risky hallucination hazard to a practical developer tool.

The Blind Spot of Text-Only Spatial AI

To understand why GeoSQL is necessary, you have to look at where traditional LLM coding assistants fall down when handling geospatial data.

First, there is the schema and dialect problem. Spatial SQL is not standardized. PostGIS uses one set of functions, Google BigQuery uses another, and Snowflake has its own quirks. An LLM writing spatial SQL from a generic prompt will often hallucinate functions or mix dialects.

Second, coordinate reference systems are a constant source of silent failures. If your points table uses EPSG:4326 (WGS 84 latitude/longitude) and your polygons use EPSG:3857 (Web Mercator meters), a naive spatial join will either fail outright or return zero results. A text-only LLM has no easy way to debug this because the SQL syntax itself looks correct.

Finally, there is the cost. Running an unoptimized spatial query over millions of rows in BigQuery can scan terabytes of data in seconds. Without strict bounding box filters or H3 index partitioning, an autonomous agent can easily run up a massive bill before you realize it is stuck in an error-correction loop.

How GeoSQL Works: The Map-in-the-Loop Architecture

GeoSQL, developed by the team behind Dekart, operates as an agent skill for Claude Code, Codex, and GitHub Copilot. Instead of just generating a query and hoping for the best, it runs an active feedback loop that mimics how a human GIS analyst works.

flowchart TD
    A[User Prompt] --> B[Schema Discovery]
    B --> C[Write Spatial SQL]
    C --> D[Cost Dry-Run]
    D -- Over Budget --> E[Rewrite with tighter BBox/H3]
    E --> D
    D -- Under Budget --> F[Execute & Validate Geometry]
    F --> G[Render Map via Dekart]
    G --> H[Multimodal Visual Check]
    H -- Error Detected --> C
    H -- Looks Correct --> I[Return Map & Data]

The process breaks down into five distinct phases:

1. Discovery: The skill queries your database metadata to learn the exact tables, columns, and types. It does not guess schemas. It is built to work with private tables as well as public datasets like Overture Maps shares on BigQuery and Snowflake.
2. SQL Generation: The agent writes spatial SQL tailored to your specific engine, using appropriate optimizations like bounding box overlap checks for partition pruning.
3. Cost Check: On BigQuery, GeoSQL runs a dry-run first to estimate the bytes scanned. It enforces a default 10 GiB billing cap. If a query is over budget, the agent automatically rewrites it to be cheaper, applying tighter bounding boxes, lower H3 resolutions, or more aggressive filters.
4. Geometry Validation: The agent runs a sanity check on the output, computing total area for polygons or total length for lines to verify they align with domain expectations.
5. Visual Feedback: This is the core differentiator. GeoSQL renders the query results on a map using Dekart, an open-source Kepler.gl backend. The agent then inspects the rendered image. If it sees a geometry-class error, such as mistaking a neighborhood polygon for a metro-area perimeter, it self-corrects and rewrites the query.

According to the project's benchmarks, adding this visual feedback loop results in a 4x improvement on geospatial tasks compared to text-only validation. Without the map, agents frequently miss structural errors like double-counting overlapping features or selecting the wrong join keys.

Developer Workflow and Setup

To use GeoSQL, you do not need a SaaS account. The tool can run entirely locally or self-hosted.

You can install the Python package and initialize the interactive mode:

pip install geosql && geosql

If you are using Claude Code, you can add it directly as a skill:

/plugin marketplace add dekart-xyz/geosql
/plugin install geosql

For map rendering and PostGIS support, GeoSQL relies on Dekart. You can spin up a local Dekart instance using Docker:

docker run -p 8080:8080 dekartxyz/dekart

Then, initialize the CLI to connect to your database:

pip install dekart && dekart init

Once connected, you can issue complex spatial prompts directly to your agent. For example, if you are analyzing electric vehicle infrastructure, you can run:

/geosql Show EV charger density along major roads and render a map

The agent will discover your roads and chargers tables, write the appropriate ST_DWithin or ST_Distance query, run a cost check, execute it, and render the resulting density map in your browser via Dekart.

Because GeoSQL uses your local CLI authentication (such as bq or snow), your database credentials never leave your machine or go to the LLM provider. Only the schema metadata, generated SQL, and rendered map images are processed by the agent.

The Verdict

GeoSQL is a highly practical addition to the developer toolbelt, especially for teams working with large spatial datasets in BigQuery, Snowflake, or PostGIS.

The "map-in-the-loop" approach is not a gimmick. It addresses the fundamental limitation of LLMs in spatial contexts: the inability to evaluate geometry through text alone. By giving the agent eyes via Dekart and Kepler.gl, it eliminates the silent failures that make raw LLM-generated spatial SQL so dangerous.

For developers, the cost guardrails alone make it worth trying. The default 10 GiB billing cap on BigQuery prevents the kind of runaway agent behavior that can lead to unpleasant surprises on your monthly cloud bill. While you will still want to review complex queries before dropping them into production pipelines, GeoSQL makes the exploratory phase of spatial analysis significantly faster.