🔶 Geosql：面向地理空间数据的 Claude/Codex 技能

Claude、Codex 和 GitHub Copilot 技能，面向在 PostGIS、BigQuery、Snowflake 和 Wherobots 上处理地理空间数据的数据科学家和分析师。

注意：不需要 SaaS 账户。100% 本地或自托管运行。

加入地图循环后，地理空间任务的性能提升 4 倍。

使用 Python（交互模式）：

pip install geosql && geosql

直接安装到支持的 Agent 中：

geosql install claude geosql install codex geosql install copilot

或在 Claude Code 中：

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

执行 geosql install copilot 后，在 VS Code Copilot 或 Copilot CLI 中使用以下提示词使用 GeoSQL：

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

安装 Dekart 以支持地图渲染和 PostGIS

GeoSQL 可选使用 Dekart：一个开源 Kepler.gl 后端，带有 PostGIS、BigQuery 和 Snowflake 连接器。你可以通过一条 Docker 命令在本地运行 Dekart，在自己的基础设施上自托管 ，或使用 Dekart Cloud。

本地运行 Dekart（若要使用 Dekart Cloud 则跳过此步）：

docker run -p 8080:8080 dekartxyz/dekart

安装 Dekart CLI：

pip install dekart && dekart init

按照 CLI 和 dekart 提示连接你的 PostGIS、BigQuery、Snowflake 或 Wherobots 数据库。

在你的 Agent 中尝试的示例提示词：

房地产分析：

/geosql 显示渥太华学校可达性较差的建筑，并渲染为地图

选址：

/geosql 基于 POI 共现和到最近竞争对手的距离，在西雅图找出前 10 个体育用品商店选址，并创建地图

电动汽车充电基础设施：

/geosql 创建罗马尼亚主要道路沿线电动汽车充电桩密度地图，突出显示距离高速公路、主干道或一级道路 5 公里内的充电站数量

GeoSQL 运行一个包含地图的 Agent 循环。

1. 发现：技能探索你的数据仓库元数据（表、列、类型），而不是猜测模式。适用于 BigQuery 和 Snowflake 上的 Overture Maps 共享数据，以及你在 PostGIS、BigQuery、Snowflake 或 Wherobots 上的私有表。
2. SQL：Agent 使用适合你引擎的函数编写空间 SQL（ST_INTERSECTS、ST_DISTANCE、H3、用于分区剪枝的边界框重叠等）。
3. 成本检查：在 BigQuery 上，每个查询都会先进行干运行以预估扫描字节数。默认强制 10 GiB 的计费上限。超预算的查询会被重写为更廉价的版本（更紧的边界框、更低的 H3 分辨率、更多过滤器），而不是直接执行。
4. 几何验证：Agent 计算总面积（多边形）或总长度（线条）作为合理性检查，并与领域知识进行交叉检查。
5. 地图反馈：当可用时，Agent 通过 Dekart 渲染结果，查看渲染后的图像，并纠正纯文本循环会忽略的几何错误。正是这个循环带来了 4 倍的提升。

该技能使用你本地的 CLI 认证（bq、snow、dekart），因此仓库凭证永远不会发送给 Agent。

GeoSQL 附带一个可重现的评估套件，位于 evals/ 目录下。每个案例都断言特定的行为（成本护栏、验证步骤、正确的结果），而不仅仅是“Agent 是否回答了”。

当前套件的结果：

平均每回合 3085 个 token，耗时 72 秒。

上面的 4 倍提升 图表比较了有与没有地图循环步骤的相同任务集。没有地图时，Agent 的纯文本验证会遗漏几何类错误（将街区多边形误认为都市区域周界、重复计算重叠要素、在坐标系参考上选错连接键）。将渲染后的地图作为一个工具调用，能让 Agent 看到这些错误并进行自我纠正。

你自己运行该套件：

请参阅 evals/RUNBOOK.md 了解设置以及如何添加新案例。欢迎提交包含新评估案例的 PR。

Claude, Codex, and GitHub Copilot 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.

With Python (interactive mode):

pip install geosql && geosql

Install directly into a supported agent:

geosql install claude
geosql install codex
geosql install copilot

Or in Claude Code:

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

After geosql install copilot, use GeoSQL from VS Code Copilot or Copilot CLI with prompts such as:

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

Install Dekart for map rendering and PostGIS support

GeoSQL optionally uses Dekart: an open-source Kepler.gl backend with connectors for PostGIS, BigQuery, and Snowflake. You can run Dekart locally with one docker command, self-host it on your own infrastructure, or use Dekart Cloud.

Run Dekart locally (skip this step to use Dekart Cloud):

docker run -p 8080:8080 dekartxyz/dekart

Install the Dekart CLI:

pip install dekart && dekart init

Follow CLI and dekart prompts to connect your PostGIS, BigQuery, Snowflake or Wherobots database.

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.

GeoSQL runs an agent loop with a map in it.

1. 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.
2. 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).
3. 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.
4. Geometry validation. The agent computes total area (polygons) or total length (lines) as a sanity check, and cross-checks against domain knowledge.
5. 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.

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:

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:

See evals/RUNBOOK.md for setup and how to add new cases. PRs with new evals welcome.