项目地址: https://github.com/duckdb/duckdb-spatial
官方文档: https://duckdb.org/docs/stable/core_extensions/spatial/overview
函数参考: https://duckdb.org/docs/stable/core_extensions/spatial/functions
GEOMETRY 类型: https://duckdb.org/docs/stable/sql/data_types/geometry
最新版本: DuckDB 2.0.0(截至 2026-11,PyPI / GitHub Releases)
扩展分发: 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号);GEOMETRY 类型自 DuckDB 1.5 起内置,空间函数仍由 spatial 扩展提供
许可证: MIT
概述
DuckDB Spatial 是 DuckDB 官方的核心扩展(core extension),把列式分析数据库变成可读写地理数据的空间分析工具。它按 OGC Simple Features 模型提供空间函数,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件;GEOMETRY 数据类型自 DuckDB 1.5 起已是内置类型,但绝大多数空间函数(ST_Area、ST_Buffer、ST_Intersects 等)仍然装在 spatial 扩展里,装扩展这一步不能省。
- 零服务依赖:进程内运行,扩展按需安装,无需 PostGIS 或服务器
- 轻量几何类型:POINT_2D / LINESTRING_2D / POLYGON_2D / BOX_2D 有原生函数重载,比通用 GEOMETRY 路径快
- ST_Read 表函数:通过 GDAL 直接查询 Shapefile、GeoPackage、GeoJSON、FlatGeoBuf 等
- SQL 即分析:空间谓词、聚合(ST_Union_Agg、ST_Extent_Agg)、瓦片编码(ST_AsMVT)
- 与 Parquet/CSV/JSON 同库联查:空间表可直接 JOIN 普通表,无须导入导出
- WASM 可用:同一扩展编译为 WebAssembly,GeoLibre 与 DuckDB-WASM 前端都靠它
- 内建与扩展分层:内置的只有 ST_GeomFromWKB、ST_AsWKB、ST_AsWKT(别名 ST_AsText)、ST_Intersects_Extent(别名
&&)、ST_CRS、ST_SetCRS 这少数几个;其余 ST_* 函数要 LOAD spatial 才有
官方发布的扩展二进制(INSTALL spatial 拉的那种)已经把 GEOS、PROJ、GDAL 等依赖静态链接进扩展,机器上不需要另外安装 GDAL;只有从源码自建时才需要系统里备好这些库(vcpkg.json 里声明了 geos、proj、gdal>=3.12.4 等)。
环境准备
安装 DuckDB
# 1) Python(推荐用于脚本与 Notebook)
pip install duckdb==2.0.0
# 2) conda / mamba
conda install -c conda-forge duckdb
# 3) 官方 CLI(单文件可执行)
# Windows: 下载 duckdb_cli-windows-amd64.zip 后解压
# macOS: brew install duckdb
安装 spatial 扩展
-- DuckDB 2.0 起可用一条语句完成安装 + 加载
INSTALL AND LOAD spatial;
-- 等价的分两步写法(旧版本也支持)
INSTALL spatial;
LOAD spatial;
INSTALL 会把扩展写入用户目录(~/.duckdb/extensions///),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时空函数都会报"不存在"(内置的 ST_CRS / ST_SetCRS / ST_AsWKT 等除外)。
验证
import duckdb
con = duckdb.connect()
con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
print(con.execute("SELECT duckdb_version()").fetchone())
print(con.execute("SELECT ST_AsText(ST_Point(116.39, 39.90))").fetchone())
print(con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name='spatial'").fetchone())
print(con.execute("SELECT duckdb_proj_version()").fetchone())
预期能打印 POINT (116.39 39.9) 与 PROJ 版本号;任一失败即扩展未正确加载。
核心 API
几何构造与序列化
| 函数 | 作用 | 返回 |
|---|---|---|
| ST_Point(x, y) / ST_MakePoint(x, y) | 构造点(两者等价,后者为 PostGIS 兼容名) | GEOMETRY |
| ST_GeomFromText(wkt [, ignore_invalid]) | 从 WKT 解析 | GEOMETRY |
| ST_GeomFromGeoJSON(json) / ST_AsGeoJSON(geom) | GeoJSON fragment 互转 | GEOMETRY / JSON |
| ST_GeomFromWKB(blob) / ST_AsWKB(geom) | WKB 互转 | GEOMETRY / WKB_BLOB |
| ST_MakeEnvelope(minx, miny, maxx, maxy) | 矩形面 | GEOMETRY |
| ST_MakeLine(list_of_points) / ST_MakePolygon(ring) | 线/面构造 | GEOMETRY |
| ST_AsText(geom) / ST_AsWKT(geom) | 输出 WKT(ST_AsText 是 ST_AsWKT 的别名,两者内置) | VARCHAR |
| ST_CRS(geom) / ST_SetCRS(geom, crs) | 读取 / 设置几何的 CRS 标识(内置,DuckDB 1.5+) | VARCHAR / GEOMETRY |
SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
ST_AsText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY) AS poly,
ST_AsWKB('POINT(1 2)'::GEOMETRY)::BLOB AS wkb;
字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。CRS 在 DuckDB 里是类型的一部分而不是行内隐藏属性:GEOMETRY('OGC:CRS84')、GEOMETRY('EPSG:4326') 声明列的 CRS,用 ST_CRS / ST_SetCRS 读写,没有 PostGIS 那种 ST_SRID / ST_SetSRID 函数名。
SELECT ST_CRS('POINT(1 2)'::GEOMETRY('OGC:CRS84')); -- OGC:CRS84
SELECT typeof(ST_SetCRS('POINT(1 2)'::GEOMETRY, 'OGC:CRS84')); -- GEOMETRY('OGC:CRS84')
CRS 标识必须已在系统目录注册:内置只注册少数常见 CRS(如 OGC:CRS84、OGC:CRS83),加载 spatial 后才会注册 EPSG 全量 7000+ 套,可用 SELECT * FROM duckdb_coordinate_systems(); 查看。带 CRS 的 GEOMETRY 列要求存储版本 v1.5.0 及以上(DuckDB 2.0 的默认存储版本已满足)。
空间关系谓词
| 函数 | 说明 |
|---|---|
| ST_Intersects(a, b) | 相交(含接触) |
| ST_Contains(a, b) / ST_Within(a, b) | 包含 / 被包含 |
| ST_Covers(a, b) / ST_CoveredBy(a, b) | 覆盖(边界计入,比 Contains 宽松) |
| ST_Disjoint(a, b) | 不相交 |
| ST_Touches(a, b) / ST_Crosses(a, b) | 接触 / 穿越 |
| ST_DWithin(a, b, dist) | 距离小于阈值 |
| ST_Intersects_Extent(a, b) | 仅比较包围盒,最快的粗筛 |
-- 点落在面内:用 EXISTS 半连接,避免笛卡尔积
SELECT c.name
FROM cities c
WHERE EXISTS (
SELECT 1 FROM countries k
WHERE ST_Intersects(k.geom, c.geom)
);
度量与构造
| 函数 | 说明 | 单位 |
|---|---|---|
| ST_Area(geom) | 平面面积(非面返回 0) | 与坐标系一致 |
| ST_Area_Spheroid(geom) | 椭球面积,假定输入为 EPSG:4326 | 平方米 |
| ST_Length(geom) | 平面长度 | 与坐标系一致 |
| ST_Length_Spheroid(geom) | 椭球长度 | 米 |
| ST_Distance(a, b) | 平面距离(忽略 Z) | 与坐标系一致 |
| ST_Distance_Sphere(a, b) | 大圆距离 | 米 |
| ST_Centroid(geom) | 质心 | GEOMETRY |
| ST_Buffer(geom, dist [, num_triangles]) | 缓冲,num_triangles 默认 8 | 与坐标系一致 |
| ST_Simplify / ST_SimplifyPreserveTopology | 简化 | — |
| ST_MakeValid / ST_IsValid | 修复 / 校验 | — |
-- 经纬度下 ST_Area 的单位是"平方度",要米制面积就用椭球版本
SELECT name,
ST_Area(geom) AS planar_deg2,
ST_Area_Spheroid(geom) AS spheroid_m2
FROM countries
ORDER BY spheroid_m2 DESC
LIMIT 5;
坐标转换
-- 显式给出源与目标 CRS;always_xy 决定是否强制 x=经度
SELECT ST_AsText(
ST_Transform(ST_Point(116.39, 39.90), 'EPSG:4326', 'EPSG:3857')
);
-- 包围盒同样可以转换
SELECT ST_Transform({min_x: -180, min_y: -85, max_x: 180, max_y: 85}::BOX_2D,
'EPSG:4326', 'EPSG:3857');
CRS 字符串支持 PROJ 认得的写法('EPSG:4326'、'+proj=longlat +datum=WGS84'、WKT)。ST_Transform 不会替你猜坐标系,源 CRS 必须由你给出。
聚合与瓦片
| 函数 | 说明 |
|---|---|
| ST_Union_Agg(geom) | 合并要素(GEOS union) |
| ST_Extent_Agg(geom) | 最小包围盒多边形 |
| ST_Intersection_Agg(geom) | 批量求交 |
| ST_CoverageUnion_Agg(geom) | 覆盖合并(共享边界时更快) |
| ST_AsMVT(row, layer_name, extent, geom_col, id_col) | 生成 Mapbox Vector Tile |
| ST_AsMVTGeom(geom, bounds, extent, buffer, clip) | 裁剪到瓦片边界 |
-- 按省合并成一条 MultiPolygon,并给出总包围盒
SELECT province,
ST_AsText(ST_Union_Agg(geom)) AS merged,
ST_AsText(ST_Extent_Agg(geom)) AS bbox
FROM counties
GROUP BY province;
文件读写(GDAL 表函数)
| 函数 | 说明 |
|---|---|
| ST_Read(path, ...) | 读矢量文件,参数见下表 |
| ST_Read_Meta(path) | 只读元数据(图层、CRS、字段) |
| ST_ReadSHP(path, encoding) | 不依赖 GDAL 的 Shapefile 读取(快,基础类型) |
| ST_ReadOSM(path) | 直接解析 .osm.pbf,输出原始 Nodes/Ways/Relations |
| ST_Drivers() | 列出编译进来的 GDAL 驱动 |
常用 ST_Read 参数:
| 参数 | 类型 | 说明 |
|---|---|---|
| layer | VARCHAR | 图层名或索引(0 起);多图层文件必给 |
| spatial_filter_box | BOX_2D | 按包围盒过滤(部分驱动可下推) |
| spatial_filter | WKB_BLOB | 按任意几何过滤 |
| open_options | VARCHAR[] | 透传 GDAL 打开选项,如 FLATTEN_NESTED_ATTRIBUTES=YES |
| allowed_drivers | VARCHAR[] | 限制可用驱动 |
| keep_wkb | BOOLEAN | 返回 wkb_geometry(WKB_BLOB)而非 GEOMETRY |
-- 单图层文件
CREATE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');
-- 指定图层 + 包围盒过滤
SELECT * FROM ST_Read('data/city.gpkg',
layer := 'buildings',
spatial_filter_box := {min_x: 116.0, min_y: 39.5,
max_x: 116.6, max_y: 40.1}::BOX_2D);
-- 先看元数据,再决定读哪个图层
SELECT unnest(layers).name FROM ST_Read_Meta('data/city.gpkg');
替换扫描(replacement scan):.shp、.gpkg、.fgb 三种扩展名可以直接当表名查,无需 ST_Read:
SELECT * FROM 'data/roads.shp' LIMIT 5;
这只是 ST_Read 的语法糖,性能一致;要传参数时仍应显式调用 ST_Read。
典型工作流:Shapefile → 空间分析 → GeoParquet
输入 data/roads.shp(线)与 data/districts.shp(面),目标是从每条道路提取落在各区的长度并输出 Parquet。
import duckdb
con = duckdb.connect("analysis.duckdb")
con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
# 1) 读入并落到持久表(避免每次查询重复解析 Shapefile)
con.execute("CREATE OR REPLACE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');")
con.execute("CREATE OR REPLACE TABLE districts AS SELECT * FROM ST_Read('data/districts.shp');")
# 2) 探明列名与 CRS
print(con.execute("DESCRIBE roads").fetchall())
print(con.execute("""
SELECT layers[1].geometry_fields[1].crs.auth_name,
layers[1].geometry_fields[1].crs.auth_code
FROM ST_Read_Meta('data/roads.shp')
""").fetchone())
# 3) 统一到投影坐标系后再算长度(米),避免把"度"当"米"
con.execute("""
CREATE OR REPLACE TABLE roads_m AS
SELECT *, ST_Transform(geom, 'EPSG:4326', 'EPSG:3857') AS geom_m,
ST_Length(ST_Transform(geom, 'EPSG:4326', 'EPSG:3857')) AS length_m
FROM roads;
""")
con.execute("""
CREATE OR REPLACE TABLE districts_m AS
SELECT *, ST_Transform(geom, 'EPSG:4326', 'EPSG:3857') AS geom_m
FROM districts;
""")
# 4) 叠加:相交取交线,按区汇总长度
con.execute("""
CREATE OR REPLACE TABLE road_length_by_district AS
SELECT d.name AS district,
SUM(ST_Length(ST_Intersection(r.geom_m, d.geom_m))) AS length_m
FROM roads_m r
JOIN districts_m d
ON ST_Intersects(r.geom_m, d.geom_m)
GROUP BY d.name
ORDER BY length_m DESC;
""")
# 5) 输出:几何列写成 WKB
con.execute("""
COPY (SELECT ST_AsWKB(geom_m) AS geometry, name, length_m FROM roads_m)
TO 'out/roads_m.parquet' (FORMAT parquet);
""")
print(con.execute("SELECT * FROM road_length_by_district LIMIT 10").fetchall())
输出 out/roads_m.parquet 与一张按区汇总的长度表。要点:先把 Shapefile 落到持久表(重复 ST_Read 很慢)、先投影再算长度、按区名分组而不是逐行比较。
与 Python / pandas 协作
import duckdb, geopandas as gpd
con = duckdb.connect()
con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
# 查询结果直接转 DataFrame
rows = con.execute("SELECT name, ST_AsText(geom) FROM ST_Read('data/cities.shp')").fetchdf()
# GeoDataFrame 注册成视图后即可用 SQL 查询
districts = gpd.read_file("data/districts.gpkg")
con.register("districts", districts)
print(con.execute("SELECT name, ST_Area(geom) AS area FROM districts ORDER BY area DESC LIMIT 5").fetchall())
register 只在当前会话有效;跨进程请建表或直接读文件。
输出 GeoParquet 与矢量瓦片
-- GeoParquet:几何列写成 WKB,字段名用 geometry 便于下游识别
COPY (SELECT ST_AsWKB(geom) AS geometry, name, pop FROM cities)
TO 'out/cities.parquet' (FORMAT parquet);
-- MVT:先裁剪到瓦片,再聚合
WITH tile AS (
SELECT ST_AsMVTGeom(
ST_Transform(geom, 'EPSG:4326', 'EPSG:3857'),
ST_TileEnvelope(12, 3423, 1586)
) AS geom,
name
FROM cities
WHERE ST_Intersects_Extent(
ST_Transform(geom, 'EPSG:4326', 'EPSG:3857'),
ST_TileEnvelope(12, 3423, 1586))
)
SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
性能优化
- 落表再查:对同一文件重复 ST_Read 会反复走 GDAL 解析,先 CREATE TABLE AS 物化。GDAL 是单线程的,ST_Read 无法并行。
- 先做包围盒粗筛,再看要不要空间索引:join 前用 ST_Intersects_Extent(或等价的
&&运算符)缩小候选集,再用 ST_Intersects 精确判断 —— 这一步在任何版本都有效,而且&&在 2.0 里还能吃到 GEOMETRY 列的 row-group 统计信息。DuckDB 2.0 的索引文档写明「spatial 扩展可为空间列提供 R-tree」,CREATE INDEX也支持可选的 index type;但具体能否建、建了是否被选中,取决于扩展版本与查询形态,落地前先EXPLAIN ANALYZE实测对比,别假设它一定生效。 - 优先用轻量类型:能落成 POINT_2D / POLYGON_2D 的列走原生实现,必要时用 ST_Force2D 去掉 Z/M。
- 面积/长度单位要有依据:经纬度下 ST_Area 的单位是平方度,应改用 ST_Area_Spheroid 或先投影。
- 投影一次即可:ST_Transform 是 CPU 热点,放在建表阶段,不要写在 WHERE 里逐行算。
- 减少字符串往返:几何尽量保持二进制形态,只在最终输出时 ST_AsText / ST_AsWKB。
- 大文件用列裁剪:SELECT name, geom 比 SELECT * 少读属性列。
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Extension spatial is not installed | 只写了 LOAD 没写 INSTALL,或离线环境拉不到扩展 | 先执行 INSTALL spatial;离线时复用扩展目录,或下载官方 unsigned 构建后 INSTALL ''(需 -unsigned 启动) |
| Catalog Error: Scalar Function with name ST_Intersects does not exist | 当前连接没 LOAD spatial | 每个新连接都要 LOAD spatial;Python 里可在建连后立即执行 |
| ST_Area 返回 0 或很小的数 | 输入是经纬度,单位是平方度 | 用 ST_Area_Spheroid,或先 ST_Transform 到米制投影 |
| ST_Transform 报 CRS 解析失败 | 源/目标 CRS 字符串拼错或 PROJ 未识别 | 用 'EPSG:4326' 这类标准写法;SELECT duckdb_proj_version() 确认 PROJ 可用 |
| 读 GeoPackage 只拿到第一个图层 | 多图层文件未指定 layer | 用 ST_Read_Meta 先看 layers,再 ST_Read(..., layer := '...') |
| Shapefile 中文属性乱码 | DBF 编码与默认 UTF-8 不一致 | 用 ST_ReadSHP(path, encoding := 'GBK'),或在 open_options 里给驱动指定编码 |
| 空间 join 极慢 | 没做包围盒粗筛,也没利用任何索引 | 先 ST_Intersects_Extent(&&)粗筛再 ST_Intersects 精筛;仍慢再试 CREATE INDEX 并 EXPLAIN ANALYZE 核对是否真的用上 |
| 写出的 Parquet 没有 CRS | ST_AsWKB 只写几何,不写 CRS 元数据 | 落盘后用 GeoPandas/GDAL 补写 crs,或用 ogr2ogr 转出 |
| ST_ReadOSM 只返回 node/way 原始表 | 该函数不做几何装配 | 需要成品几何时改用 ST_Read 的 OSM 驱动 |
| Unknown coordinate system / unrecognized coordinate system | CRS 标识未注册:EPSG 全集由 spatial 扩展注册,只装了 DuckDB 没 LOAD spatial 时只剩少数内置 CRS | 先 LOAD spatial 再写 GEOMETRY('EPSG:4326');仍失败则 SELECT * FROM duckdb_coordinate_systems() 核对标识,必要时 SET ignore_unknown_crs = true 显式丢弃未知 CRS |
| GEOMETRY columns with coordinate reference system identifiers are not supported in storage versions prior v1.5.0 | 带 CRS 的 GEOMETRY 列要求存储版本 v1.5.0+,旧库文件读不了 | 用 ATTACH 'file.db' (STORAGE_VERSION 'v1.5.0') 重建库,或先用 EXPORT DATABASE / IMPORT DATABASE 迁移存储格式 |
| pip install duckdb 装到 1.x、没有 2.0 的新行为 | DuckDB 2.0 要求 Python 3.11+,3.10 上 pip 只会解析到 1.x | 升级 Python 到 3.11+ 后重装;python -c "import duckdb; print(duckdb.__version__)" 确认 |
AI 使用建议
- 先验扩展再写 SQL:执行前跑 SELECT extension_name, loaded FROM duckdb_extensions() WHERE extension_name='spatial'; 确认 loaded=true;未加载就先 LOAD,不要把"函数不存在"当语法错误去改。
- 版本敏感:2.0.0 与旧版函数集合有差异(ST_Area_Spheroid、ST_CoverageUnion_Agg 属较新函数;GEOMETRY 类型自 1.5 起内置,ST_CRS / ST_SetCRS 也随之内置)。写示例前用 SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'; 探测实际可用函数。
- 2.0 迁移要先看存储格式:DuckDB 2.0 默认写 storage version 69,旧版本(如 1.5.x)读不了;跨版本共享库文件前先用
duckdb my.db -storage-version v1.5.6或config={"storage_compatibility_version": "v1.5.0"}指定存储版本,迁移方法见官方 Migrating to DuckDB 2.0。 - CRS 是类型的一部分:
GEOMETRY('EPSG:4326')与无 CRS 的 GEOMETRY 是不同的类型,多数二元空间函数要求两侧 CRS 一致;跨 CRS 先 ST_Transform,不要只靠 SET 全局开关去改轴序。 - 大文件不要整读进内存:优先用 ST_Read 的 spatial_filter_box / layer 参数与 Parquet 列裁剪;反复查询时先落表。
- 验证产物:写完 Parquet/MVT 后回读核对 count、ST_IsValid、ST_GeometryType 分布,以及坐标范围是否落在预期 CRS 内。
- 写操作确认:COPY ... TO、CREATE OR REPLACE TABLE、DROP TABLE 会覆盖文件或表;执行前确认目标路径已被授权覆盖。
相关技能
- postgis — 服务端空间数据库,DuckDB 的常见替代:../postgis/SKILL.md
- geopandas — Python 矢量分析,可与 DuckDB 互转:../geopandas/SKILL.md
- gdal — ST_Read 背后的读写引擎与格式转换:../gdal/SKILL.md
- proj — CRS 定义与 ST_Transform 的底层库:../proj/SKILL.md
- geolibre — 浏览器里用 DuckDB-WASM Spatial 做 SQL 分析:../geolibre/SKILL.md
参考资源
- 扩展仓库:https://github.com/duckdb/duckdb-spatial
- 函数总表:https://duckdb.org/docs/stable/core_extensions/spatial/functions
- GEOMETRY 数据类型:https://duckdb.org/docs/stable/sql/data_types/geometry
- 内置几何函数:https://duckdb.org/docs/stable/sql/functions/geometry
- DuckDB 2.0 迁移指南:https://duckdb.org/docs/stable/operations_manual/migration
- DuckDB 文档:https://duckdb.org/docs/stable/