mcpField
S
spatial

spatial

github.com/duckdb数据与数据库613734 次安装28 周前更新
代码仓库

关于 spatial

使用 DuckDB spatial 扩展回答空间问题，可分析用户提供的文件；未提供文件时，可用 Overture Maps 查询地点、建筑、道路或边界。

主要功能

  1. 01使用 DuckDB 查询空间数据
  2. 02用 Overture Maps 查询地点信息
  3. 03分析用户提供的空间文件
  4. 04执行距离、包含关系和 H3 分析
  5. 05将空间结果导出为 GeoJSON

适用场景

  1. 01查找附近地点、建筑或道路
  2. 02测量地点之间的距离
  3. 03判断点是否位于多边形内
  4. 04分析密度或热点

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/duckdb/duckdb-skills --skill spatial

安装后在 Claude Code 中输入/spatial确认已加载。

附带文件references/functions.mdreferences/overture.md

详细介绍

你将使用 DuckDB 的 spatial 扩展，并在需要时使用 Overture Maps 这一免费的全球数据源，回答空间问题。

问题或文件：$0 补充上下文：${1:-}

步骤 1 — 了解用户的需求

对问题进行分类：

模式数据源关键函数
“查找 Y 附近的 X”（未提供用户文件）S3 上的 Overture MapsST_Distance_Spheroid、bbox 过滤
“A 和 B 之间有多远”地理编码或用户数据ST_Distance_Spheroid
“哪些点落在多边形内”用户文件ST_Contains
“分析这个 GeoJSON/Shapefile/GPX”用户文件ST_Read、测量函数
“显示密度/热点”用户数据或 Overture 数据H3 六边形分箱
“转换为 GeoJSON/GeoPackage”用户文件COPY TO (FORMAT GDAL)
“统计区域内的建筑/道路数量”Overture Mapsbbox 过滤 + 聚合

如果问题涉及真实世界的地点、POI、建筑、道路或边界，且用户未提供文件，请使用 Overture Maps——读取 references/overture.md 了解 S3 路径和架构。

如需空间函数的语法，请读取 references/functions.md。

步骤 2 — 编写并运行查询

始终从以下内容开始：

LOAD spatial;
SET geometry_always_xy = true;

按需添加扩展：

  • Overture/远程数据：LOAD httpfs; CREATE SECRET (TYPE S3, PROVIDER config, REGION 'us-west-2');
  • H3 六边形分箱：INSTALL h3 FROM community; LOAD h3;
关键原则

先进行 bbox 过滤——查询 Overture 时，始终在使用任何空间函数之前，按 bbox.xmin/xmax/ymin/ymax 过滤。这会使用 Parquet 谓词下推，避免下载完整数据集。

始终设置 geometry_always_xy = true——这可确保所有空间函数都将坐标解释为经度、纬度（这是 Overture、GeoJSON 和大多数数据源采用的标准）。若不设置，椭球体函数会默认纬度在前，导致结果错误。

实际距离使用椭球体函数——ST_Distance_Spheroid 返回 WGS84 椭球体上的米数。普通的 ST_Distance 使用平面坐标，无法为经纬度提供有意义的结果。**重要：**椭球体函数（ST_Distance_Spheroid、ST_Area_Spheroid 等）需要 POINT_2D 输入，而非通用的 GEOMETRY。Overture 几何列的类型为 GEOMETRY('OGC:CRS84')，无法直接转换。请先提取坐标：

ST_Point(ST_X(geometry), ST_Y(geometry))::POINT_2D

CSV 中的经纬度需要转换——使用 ST_Point(longitude, latitude)（经度在前）。这是最常见的易错点。

在单次 bash 调用中运行查询：

duckdb -c "
LOAD spatial;
<ADDITIONAL_SETUP>
<YOUR_QUERY>
"

步骤 3 — 展示结果

  • 对于表格结果：直接展示数据
  • 对于空间结果：可考虑导出为 GeoJSON 以便可视化（COPY TO 'result.geojson' WITH (FORMAT GDAL, DRIVER 'GeoJSON')）
  • 对于距离/面积结果：使用易读的单位（较大距离用 km，较小距离用 m）
  • 对于密度/热点结果：描述其分布规律，并提出可导出以供可视化

如果查询失败：

  • duckdb: command not found → 委派给 /duckdb-skills:install-duckdb
  • 缺少扩展 → INSTALL spatial; LOAD spatial; 或 INSTALL h3 FROM community; LOAD h3;
  • S3 访问被拒绝 → 建议检查 AWS 凭据
  • 使用 Overture 时没有结果 → 扩大 bbox、检查类别拼写，或尝试更宽泛的搜索

评论

支持 Markdown