Showing AI a map boosted spatial query accuracy 4×

GeoSQL is a geospatial analysis skill (plugin) installable on Claude, Codex, and GitHub Copilot. It works by taking a natural-language question, having the AI compose a spatial SQL query for the connected database, executing it, rendering the results on an interactive map, and then showing the map back to the AI so it can visually validate the output and correct any errors before reporting back to the user.

The problem it addresses stems from the nature of spatial data errors. In a typical AI agent workflow, the system receives query results as a text table—for instance, school accessibility rankings by London borough—and reports success. But the underlying data might contain a geometric error: City of London (about 3 km²) might be mapped to the Greater London polygon (about 1,572 km²), a mistake that produces plausible numbers but is visually absurd. A text-only agent passes this through; a human reviewing a map would spot it instantly. GeoSQL closes this gap by showing the AI a rendered map. The tool also manages database dialect differences (PostGIS, BigQuery, and Snowflake each use different spatial function syntax and coordinate-system conventions), preflight-checks query cost on BigQuery (with a default ceiling of 10GiB to prevent runaway bills), and validates results for physical impossibilities (e.g., a borough larger than the city containing it).

The workflow unfolds in five steps. First, the AI explores the connected database's actual schema and column metadata rather than guessing. Second, it writes SQL using the correct spatial functions for that database. Third (BigQuery only), it estimates how many gigabytes the query will scan; if the estimate exceeds 10GiB, it automatically rewrites the query to add filters or narrow the search scope. Fourth, it performs a sanity check on the result—computing total area for polygons or total length for lines to spot obvious contradictions. Fifth, it renders the result via Dekart (a self-hosted backend for Kepler.gl, Uber's open-source map visualization library) and feeds the rendered map image back to the AI. If the AI spots a visual anomaly—a polygon that is impossibly large, a cluster of points in the ocean—it modifies the SQL and re-runs the entire loop.

GeoSQL's own benchmark showed a 4× performance difference when the map-feedback loop was enabled versus disabled. Geometric errors that passed text validation alone were caught as soon as the map was rendered. The tool supports on-premises deployment via Docker and does not require a SaaS account; it uses the user's local database CLI credentials (bq, snow, etc.), so warehouse passwords are never passed to the AI. Limitations include dependence on Dekart for the map-feedback accuracy gain, cost guards only on BigQuery, a small public benchmark (three cities, eight test cases), and the need for additional setup in air-gapped networks where package installation is restricted. For organizations managing spatial data in closed environments, GeoSQL plus Dekart offers a way to run AI-assisted spatial analysis on-premises without moving data to external services.

The core problem GeoSQL solves is a blind spot in AI reasoning: an AI agent can execute a perfectly valid SQL query and receive numerically plausible results without ever realizing the geometry is wrong. A polygon boundary might be swapped, a point might be plotted in water, or a region might be counted twice—none of these errors show up in a table of numbers. The article illustrates this with the example of City of London being mapped to Greater London's boundary; the query runs, the numbers look reasonable, but the error is instantly visible on a map.

The technical contribution is not new spatial SQL capability, but a feedback loop that lets AI see the results. Each step in GeoSQL's pipeline addresses a real friction point: it explores the actual database schema rather than guessing, automatically selects the right spatial functions for each database (PostGIS uses ST_Distance, BigQuery uses H3 grid aggregation, etc.), and checks query cost before execution on BigQuery to avoid surprise bills. But the decisive step is step 5—rendering the result as a map and feeding the map image back to the AI. The article reports that this map-feedback loop improved accuracy 4×, with errors that passed text validation caught immediately by visual inspection.

The limitations are honest and material. The 4× improvement applies only when Dekart is connected; without it, there is no visual feedback. Cost guards exist only on BigQuery. The public benchmark is small (three cities, eight cases), so enterprises need to validate performance on their own data. For on-premises and air-gapped environments, though—where organizations cannot send data to cloud AI services—GeoSQL plus Dekart offers a way to run AI-assisted spatial analysis without leaving the internal network.