@dsh-gis/dsh-opengis-skill 0.1.3 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +40 -0
- package/README.md +48 -22
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/adaptations/brutile.md +8 -0
- package/adaptations/cesiumjs.md +8 -0
- package/adaptations/common.md +16 -0
- package/adaptations/deck-gl.md +8 -0
- package/adaptations/duckdb-spatial.md +8 -0
- package/adaptations/gdal-api.md +8 -0
- package/adaptations/gdal.md +8 -0
- package/adaptations/geolibre.md +8 -0
- package/adaptations/geometry-api-java.md +8 -0
- package/adaptations/geometry-api-net.md +8 -0
- package/adaptations/geonode.md +8 -0
- package/adaptations/geopandas.md +8 -0
- package/adaptations/geopipe-agent.md +8 -0
- package/adaptations/geoserver-cloud.md +8 -0
- package/adaptations/geoserver-rest-api.md +8 -0
- package/adaptations/geoserver.md +8 -0
- package/adaptations/geotools.md +8 -0
- package/adaptations/grass-gis.md +8 -0
- package/adaptations/jts.md +8 -0
- package/adaptations/kepler-gl.md +8 -0
- package/adaptations/leaflet.md +8 -0
- package/adaptations/mapbox-gl-js.md +8 -0
- package/adaptations/mapserver.md +8 -0
- package/adaptations/mapsui.md +8 -0
- package/adaptations/nettopologysuite.md +8 -0
- package/adaptations/opengis-all.md +8 -0
- package/adaptations/opengis-daf.md +8 -0
- package/adaptations/opengis-utils-for-java.md +8 -0
- package/adaptations/opengis-utils-for-net.md +8 -0
- package/adaptations/openlayers.md +8 -0
- package/adaptations/pdal.md +8 -0
- package/adaptations/postgis.md +8 -0
- package/adaptations/proj.md +8 -0
- package/adaptations/projnet4geoapi.md +8 -0
- package/adaptations/pyqgis.md +8 -0
- package/adaptations/qgis-process.md +8 -0
- package/adaptations/qgis-server.md +8 -0
- package/adaptations/shapely.md +8 -0
- package/adaptations/sharpmap.md +8 -0
- package/adaptations/spatialite.md +8 -0
- package/adaptations/whitebox-tools.md +8 -0
- package/assets/brutile/SKILL.md +289 -0
- package/assets/cesiumjs/SKILL.md +73 -23
- package/assets/deck-gl/SKILL.md +19 -20
- package/assets/duckdb-spatial/SKILL.md +370 -0
- package/assets/gdal/SKILL.md +50 -21
- package/assets/gdal-api/SKILL.md +6 -4
- package/assets/geolibre/SKILL.md +364 -0
- package/assets/geometry-api-java/SKILL.md +5 -6
- package/assets/geometry-api-net/SKILL.md +65 -21
- package/assets/geonode/SKILL.md +347 -0
- package/assets/geopandas/SKILL.md +17 -15
- package/assets/geopipe-agent/SKILL.md +25 -20
- package/assets/geoserver/SKILL.md +6 -4
- package/assets/geoserver-cloud/SKILL.md +14 -15
- package/assets/geoserver-rest-api/SKILL.md +13 -8
- package/assets/geotools/SKILL.md +7 -5
- package/assets/grass-gis/SKILL.md +19 -20
- package/assets/jts/SKILL.md +7 -4
- package/assets/kepler-gl/SKILL.md +313 -0
- package/assets/leaflet/SKILL.md +41 -19
- package/assets/mapbox-gl-js/SKILL.md +18 -19
- package/assets/mapserver/SKILL.md +17 -19
- package/assets/mapsui/SKILL.md +85 -48
- package/assets/nettopologysuite/SKILL.md +91 -20
- package/assets/opengis-all/SKILL.md +78 -270
- package/assets/opengis-all/reference/data-stages.md +262 -4
- package/assets/opengis-daf/SKILL.md +6 -5
- package/assets/opengis-utils-for-java/SKILL.md +52 -39
- package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
- package/assets/opengis-utils-for-net/SKILL.md +105 -39
- package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
- package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
- package/assets/openlayers/SKILL.md +66 -9
- package/assets/pdal/SKILL.md +21 -17
- package/assets/postgis/SKILL.md +61 -11
- package/assets/proj/SKILL.md +28 -30
- package/assets/projnet4geoapi/SKILL.md +299 -0
- package/assets/pyqgis/SKILL.md +28 -20
- package/assets/qgis-process/SKILL.md +71 -22
- package/assets/qgis-server/SKILL.md +20 -20
- package/assets/shapely/SKILL.md +132 -75
- package/assets/sharpmap/SKILL.md +93 -50
- package/assets/spatialite/SKILL.md +365 -0
- package/assets/whitebox-tools/SKILL.md +269 -0
- package/lib/adaptations.d.ts +47 -0
- package/lib/adaptations.js +268 -0
- package/lib/index.d.ts +1 -1
- package/lib/index.js +14 -2
- package/lib/skill-file.js +31 -7
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +12 -2
- package/upstream.json +56 -40
package/assets/cesiumjs/SKILL.md
CHANGED
|
@@ -21,7 +21,7 @@ tags:
|
|
|
21
21
|
>
|
|
22
22
|
> **Sandcastle:** <https://sandcastle.cesium.com/>
|
|
23
23
|
>
|
|
24
|
-
> **最新版本:** 1.146.0(截至2026-10,npm `cesium`)
|
|
24
|
+
> **最新版本:** 1.146.0(截至 2026-10,npm `cesium`)
|
|
25
25
|
>
|
|
26
26
|
> **许可证:** Apache-2.0
|
|
27
27
|
|
|
@@ -40,28 +40,38 @@ CesiumJS 提供:
|
|
|
40
40
|
|
|
41
41
|
## 安装
|
|
42
42
|
|
|
43
|
+
### 方式一:npm
|
|
44
|
+
|
|
43
45
|
```bash
|
|
44
46
|
npm install cesium
|
|
47
|
+
npm ls cesium # 验证:应显示 cesium@1.146.0
|
|
45
48
|
```
|
|
46
49
|
|
|
47
|
-
```html
|
|
48
|
-
<link href="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
|
|
49
|
-
<script src="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Cesium.js"></script>
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
> **1.146 变更:** 数学/几何/时间/工具类被拆分为新包 `@cesium/core`(`cesium@1.146.0` 依赖 `@cesium/core@^0.1.0`)。从 `cesium` 主包导入的代码不受影响;直接按子路径引用 `@cesium/engine` 的代码需改从 `@cesium/core` 导入(旧导出计划在后续版本移除,1.146 仍可用)。
|
|
53
|
-
|
|
54
|
-
### Vite 集成
|
|
55
|
-
|
|
56
50
|
```js
|
|
57
51
|
import { defineConfig } from 'vite';
|
|
58
52
|
import cesium from 'vite-plugin-cesium';
|
|
53
|
+
|
|
59
54
|
export default defineConfig({ plugins: [cesium()] });
|
|
60
55
|
```
|
|
61
56
|
|
|
62
|
-
###
|
|
57
|
+
### 方式二:CDN
|
|
63
58
|
|
|
64
|
-
|
|
59
|
+
```html
|
|
60
|
+
<link href="https://cdn.jsdelivr.net/npm/cesium@1.146.0/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
|
|
61
|
+
<script src="https://cdn.jsdelivr.net/npm/cesium@1.146.0/Build/Cesium/Cesium.js"></script>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# 验证 CDN 版本可达
|
|
66
|
+
curl.exe -I https://cdn.jsdelivr.net/npm/cesium@1.146.0/Build/Cesium/Cesium.js # 期望 200
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 打包器接入
|
|
70
|
+
|
|
71
|
+
- **Vite**:用 `vite-plugin-cesium`,按上面的 `vite.config.js` 注册,插件负责拷贝静态资源
|
|
72
|
+
- **Webpack**:将 `node_modules/cesium/Build/Cesium/{Workers,Assets,Widgets}` 拷到输出目录,并在入口最早处设置 `window.CESIUM_BASE_URL`
|
|
73
|
+
|
|
74
|
+
> **1.146 变更:** 数学/几何/时间/工具类被拆分为新包 `@cesium/core`(`cesium@1.146.0` 依赖 `@cesium/core@^0.1.0`)。从 `cesium` 主包导入的代码不受影响;直接按子路径引用 `@cesium/engine` 的代码需改从 `@cesium/core` 导入(旧导出计划在后续版本移除,1.146 仍可用)。
|
|
65
75
|
|
|
66
76
|
---
|
|
67
77
|
|
|
@@ -231,11 +241,51 @@ viewer.trackedEntity = entity;
|
|
|
231
241
|
|
|
232
242
|
## 典型工作流
|
|
233
243
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
244
|
+
以「GeoJSON 点位 + 倾斜摄影 3D Tiles」为例,输入 `data/poi.geojson` 与 `/tiles/tileset.json`,输出可点击拾取的三维场景。
|
|
245
|
+
|
|
246
|
+
1. **初始化 Viewer**:`new Cesium.Viewer('cesiumContainer', { terrainProvider: await Cesium.createWorldTerrainAsync() })`
|
|
247
|
+
2. **加载矢量数据**:`GeoJsonDataSource.load()` → `viewer.dataSources.add(ds)` → `viewer.flyTo(ds)`
|
|
248
|
+
3. **加载 3D Tiles**:`Cesium3DTileset.fromUrl()` → `scene.primitives.add(tileset)` → `viewer.zoomTo(tileset)`
|
|
249
|
+
4. **添加交互**:`ScreenSpaceEventHandler` + `scene.pick()` 取 `picked.id`,`camera.pickEllipsoid()` 取经纬度
|
|
250
|
+
5. **性能与释放**:静态要素用 Primitive,`requestRenderMode = true`,卸载时 `tileset.destroy()` / `viewer.destroy()`
|
|
251
|
+
|
|
252
|
+
```js
|
|
253
|
+
import * as Cesium from 'cesium';
|
|
254
|
+
import 'cesium/Build/Cesium/Widgets/widgets.css';
|
|
255
|
+
|
|
256
|
+
Cesium.Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_ION_TOKEN;
|
|
257
|
+
|
|
258
|
+
const viewer = new Cesium.Viewer('cesiumContainer', {
|
|
259
|
+
terrainProvider: await Cesium.createWorldTerrainAsync(),
|
|
260
|
+
timeline: false,
|
|
261
|
+
animation: false
|
|
262
|
+
});
|
|
263
|
+
|
|
264
|
+
// 1) GeoJSON 点位:统一改成扁平圆点,避免默认图钉遮挡
|
|
265
|
+
const ds = await Cesium.GeoJsonDataSource.load('/data/poi.geojson', { clampToGround: true });
|
|
266
|
+
viewer.dataSources.add(ds);
|
|
267
|
+
for (const entity of ds.entities.values) {
|
|
268
|
+
entity.billboard = undefined;
|
|
269
|
+
entity.point = new Cesium.PointGraphics({ pixelSize: 8, color: Cesium.Color.ORANGE });
|
|
270
|
+
}
|
|
271
|
+
await viewer.flyTo(ds);
|
|
272
|
+
|
|
273
|
+
// 2) 3D Tiles:加载倾斜摄影并飞到数据范围
|
|
274
|
+
const tileset = await Cesium.Cesium3DTileset.fromUrl('/tiles/tileset.json', {
|
|
275
|
+
maximumScreenSpaceError: 16
|
|
276
|
+
});
|
|
277
|
+
viewer.scene.primitives.add(tileset);
|
|
278
|
+
await viewer.zoomTo(tileset);
|
|
279
|
+
|
|
280
|
+
// 3) 点击拾取:先试 3D Tiles / 点要素,再回退到椭球面坐标
|
|
281
|
+
const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
|
|
282
|
+
handler.setInputAction((e) => {
|
|
283
|
+
const picked = viewer.scene.pick(e.position);
|
|
284
|
+
console.log('picked:', Cesium.defined(picked) ? picked.id : null);
|
|
285
|
+
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
**验证产物**:`npm run build` 后 `python -m http.server 5173 -d dist`,`curl.exe -I http://localhost:5173/Cesium/Workers/createVerticesFromHeightmap.js` 返回 200 才说明 Workers 已随产物发布。
|
|
239
289
|
|
|
240
290
|
---
|
|
241
291
|
|
|
@@ -255,20 +305,20 @@ viewer.trackedEntity = entity;
|
|
|
255
305
|
|
|
256
306
|
| 问题 | 解决 |
|
|
257
307
|
|------|------|
|
|
258
|
-
| 黑屏 |
|
|
308
|
+
| 黑屏 / 资源 404 | 控制台报 `Unable to determine Cesium base URL automatically, try defining a global variable called CESIUM_BASE_URL.` 时,在入口最早处设 `window.CESIUM_BASE_URL = '/Cesium'`,并确认 `Workers/Assets/Widgets` 已随构建产物发布 |
|
|
259
309
|
| 模型贴地不准 | `HeightReference.CLAMP_TO_GROUND` 或地形采样 |
|
|
260
|
-
| 性能卡顿 | 启用 `requestRenderMode`,降低 `maximumScreenSpaceError
|
|
310
|
+
| 性能卡顿 | 启用 `requestRenderMode`,降低 `maximumScreenSpaceError`;静态要素改 Primitive |
|
|
311
|
+
| 报 `WebGL 2 context is required` | 浏览器/环境未提供 WebGL2(无头浏览器、远程桌面软件渲染);开启硬件加速或改用支持 WebGL2 的环境 |
|
|
261
312
|
| 国内瓦片偏移 | 使用 GCJ02→WGS84 纠偏 |
|
|
262
313
|
| Token 过期 | 不需要 ion 时不设置 token;或自托管 |
|
|
263
314
|
|
|
264
315
|
---
|
|
265
316
|
|
|
266
|
-
##
|
|
317
|
+
## AI 使用建议
|
|
267
318
|
|
|
268
|
-
-
|
|
269
|
-
- **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;Windows 下 `npm` 实为 `npm.cmd`,脚本里写 `cmd /c npm run build` 更稳;装包和大构建用后台作业,输出重定向到文件再分段读。
|
|
319
|
+
- **执行环境**:`npm install`、`npm run build` 在终端中执行;Windows 下 `npm` 实为 `npm.cmd`,脚本里写 `cmd /c npm run build` 更稳;装包和大构建放后台运行,输出重定向到文件再分段读。
|
|
270
320
|
- **先探测版本**:`npm ls cesium`(未安装时 `npm view cesium version`)。本技能按 1.146.0 编写:该版本依赖 `@cesium/core@^0.1.0`,数学/几何/时间/工具类已拆到 `@cesium/core`,低于 1.146 的工程不要照搬这条迁移建议。
|
|
271
|
-
- **验证产物**:`npm run build` 通过后用 `npx serve dist` 或 `python -m http.server 5173 -d dist` 起静态服务,用 `curl.exe -I` 检查 `http://localhost:5173/Cesium.js` 与 `.../Cesium/Widgets/widgets.css` 返回 200(404 或 text/html 说明资源没拷贝);
|
|
321
|
+
- **验证产物**:`npm run build` 通过后用 `npx serve dist` 或 `python -m http.server 5173 -d dist` 起静态服务,用 `curl.exe -I` 检查 `http://localhost:5173/Cesium.js` 与 `.../Cesium/Widgets/widgets.css` 返回 200(404 或 text/html 说明资源没拷贝);AI 助手通常看不到浏览器画面,把 URL 和预期画面交给用户,环境支持读图时用截图核对。
|
|
272
322
|
- **Ion 与部署**:`Cesium.Ion.defaultAccessToken` 从环境变量注入(Vite 用 `import.meta.env.VITE_CESIUM_ION_TOKEN`),不要写进源码或提交;黑屏先查 `window.CESIUM_BASE_URL` 与 `Workers/Assets/Widgets` 是否随构建产物发布。
|
|
273
323
|
- **坐标与性能**:定位一律 `Cesium.Cartesian3.fromDegrees(lon, lat, height)`;大量静态要素用 Primitive,少量动态要素才用 Entity;`clampToGround` 只在需要贴地时开启。
|
|
274
324
|
- **常见症状**:瓦片整体错位是国内底图的 GCJ-02 偏移,需先纠偏;ion 服务 401/403 多为 token 未设置或失效;`tileset.destroy()`、`viewer.dataSources.remove()` 不调用会持续占用显存。
|
package/assets/deck-gl/SKILL.md
CHANGED
|
@@ -20,7 +20,7 @@ tags:
|
|
|
20
20
|
>
|
|
21
21
|
> **最新版本:** 9.4.0(截至 2026-10,npm `deck.gl` 与 GitHub Release 一致)
|
|
22
22
|
>
|
|
23
|
-
> **许可证:** MIT
|
|
23
|
+
> **许可证:** MIT
|
|
24
24
|
|
|
25
25
|
## 概述
|
|
26
26
|
|
|
@@ -99,7 +99,7 @@ const deck = new Deck({
|
|
|
99
99
|
controller: true, // 设为 true 启用拖拽/缩放/旋转
|
|
100
100
|
layers: [],
|
|
101
101
|
getTooltip: ({object}) => object,
|
|
102
|
-
useDevicePixels: true //
|
|
102
|
+
useDevicePixels: true // 设 false 可显著降低高分屏下的像素开销
|
|
103
103
|
});
|
|
104
104
|
|
|
105
105
|
deck.setProps({layers: []}); // 后续增量更新,勿重建 Deck 实例
|
|
@@ -360,7 +360,7 @@ deck.pickObject({x: 100, y: 100, radius: 4, layerIds: ['stations']}); // 程序
|
|
|
360
360
|
4. 需要矢量瓦片数据时叠加 `MVTLayer`
|
|
361
361
|
5. 绑定 `getTooltip` 与 `onClick` 实现悬停与点击反馈
|
|
362
362
|
6. 数据刷新时调用 `overlay.setProps({layers: [...]})`,保持 `data` 引用稳定
|
|
363
|
-
7.
|
|
363
|
+
7. 组件卸载时 `map.removeControl(overlay)`(MapboxOverlay 无公开 `finalize()`,由 onRemove 释放内部 Deck)
|
|
364
364
|
|
|
365
365
|
```javascript
|
|
366
366
|
import {MapboxOverlay} from '@deck.gl/mapbox';
|
|
@@ -422,15 +422,15 @@ map.addControl(overlay);
|
|
|
422
422
|
|
|
423
423
|
---
|
|
424
424
|
|
|
425
|
-
##
|
|
425
|
+
## AI 使用建议
|
|
426
426
|
|
|
427
|
-
-
|
|
428
|
-
-
|
|
429
|
-
-
|
|
430
|
-
-
|
|
431
|
-
- `
|
|
432
|
-
-
|
|
433
|
-
-
|
|
427
|
+
- **执行环境**:`npm install`、`npm run build` 在终端中执行;子包多、安装输出长,重定向到文件再分段读。
|
|
428
|
+
- **先探测版本**:`npm ls deck.gl @deck.gl/core @deck.gl/layers @deck.gl/geo-layers`;所有 `@deck.gl/*` 必须是同一版本 9.4.0,混版会报 `Cannot read properties of undefined`。本技能按 9.4.0 编写。
|
|
429
|
+
- **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;WebGL 是否真出图只能由浏览器确认,AI 助手通常看不到浏览器画面,请用户看画面和控制台,环境支持读图时用截图核对。
|
|
430
|
+
- **无 GPU 环境**:无头/CI 环境无法验证 WebGL,构建通过不等于渲染正确,不要据此报告“已渲染”。
|
|
431
|
+
- **数据与坐标**:位置一律 `[经度, 纬度]`;保持 `data` 引用稳定,不要在渲染路径里 `filter`/`map` 生成新数组,否则 GPU 缓冲反复重建。
|
|
432
|
+
- **常见症状**:空白画布先查容器高度与底图;数据变了画面不变用 `updateTriggers`;tooltip 无反应是 `pickable` 默认 false。
|
|
433
|
+
- **安全与权限**:装包、起 dev server 前先征得用户同意;用 Mapbox 底图时提醒 token 与计费。
|
|
434
434
|
|
|
435
435
|
## 相关技能
|
|
436
436
|
|
|
@@ -439,13 +439,12 @@ map.addControl(overlay);
|
|
|
439
439
|
- **leaflet** — 轻量 2D 瓦片地图,适合中小数据量与简单场景:[../leaflet/SKILL.md](../leaflet/SKILL.md)
|
|
440
440
|
- **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
|
|
441
441
|
|
|
442
|
-
##
|
|
442
|
+
## 参考资源
|
|
443
443
|
|
|
444
|
-
-
|
|
445
|
-
-
|
|
446
|
-
-
|
|
447
|
-
-
|
|
448
|
-
-
|
|
449
|
-
-
|
|
450
|
-
-
|
|
451
|
-
- **安全与权限**:装包、起 dev server 前先征得用户同意;用 Mapbox 底图时提醒 token 与计费。
|
|
444
|
+
- 官方文档与示例:<https://deck.gl/>
|
|
445
|
+
- 独立模式快速上手:<https://deck.gl/docs/get-started/using-standalone>
|
|
446
|
+
- 与底图集成:<https://deck.gl/docs/get-started/using-with-map>
|
|
447
|
+
- 图层目录:<https://deck.gl/docs/api-reference/layers>
|
|
448
|
+
- `MapboxOverlay` API:<https://deck.gl/docs/api-reference/mapbox/mapbox-overlay>
|
|
449
|
+
- 性能调优指南:<https://deck.gl/docs/developer-guide/performance>
|
|
450
|
+
- 源码与发布记录:<https://github.com/visgl/deck.gl>
|
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: duckdb-spatial
|
|
3
|
+
description: "Use when doing spatial analysis inside a DuckDB database or SQL pipeline — INSTALL spatial / LOAD spatial, ST_Read over Shapefile/GeoPackage/GeoJSON, ST_Point/ST_GeomFromText, ST_Intersects/ST_Contains/ST_Buffer joins, ST_Area_Spheroid, ST_AsMVT tiles, DuckDB-WASM in the browser; also for 'Extension spatial is not installed' or spatial function does not exist, GEOMETRY vs WKB_BLOB friction, and exporting query results to GeoParquet. DuckDB 2.0 built-in spatial extension."
|
|
4
|
+
tags:
|
|
5
|
+
- duckdb
|
|
6
|
+
- sql
|
|
7
|
+
- python
|
|
8
|
+
- spatial
|
|
9
|
+
- geospatial
|
|
10
|
+
- extension
|
|
11
|
+
- vector
|
|
12
|
+
- geoparquet
|
|
13
|
+
- analysis
|
|
14
|
+
- cli
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
> **项目地址:** <https://github.com/duckdb/duckdb-spatial>
|
|
18
|
+
>
|
|
19
|
+
> **官方文档:** <https://duckdb.org/docs/stable/core_extensions/spatial/overview>
|
|
20
|
+
>
|
|
21
|
+
> **函数参考:** <https://duckdb.org/docs/stable/core_extensions/spatial/functions>
|
|
22
|
+
>
|
|
23
|
+
> **DuckDB 包(PyPI):** 2.0.0(截至 2026-10)
|
|
24
|
+
>
|
|
25
|
+
> **扩展分发:** 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号)
|
|
26
|
+
>
|
|
27
|
+
> **许可证:** MIT
|
|
28
|
+
|
|
29
|
+
## 概述
|
|
30
|
+
|
|
31
|
+
DuckDB Spatial 是 DuckDB 官方的核心扩展,把列式分析数据库变成可读写地理数据的空间分析工具。它基于 OGC Simple Features 模型增加 GEOMETRY 类型,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件。
|
|
32
|
+
|
|
33
|
+
- **零服务依赖**:进程内运行,扩展按需安装,无需 PostGIS 或服务器
|
|
34
|
+
- **轻量几何类型**:POINT_2D / LINESTRING_2D / POLYGON_2D / BOX_2D 有原生函数重载,比通用 GEOMETRY 路径快
|
|
35
|
+
- **ST_Read 表函数**:通过 GDAL 直接查询 Shapefile、GeoPackage、GeoJSON、FlatGeoBuf 等
|
|
36
|
+
- **SQL 即分析**:空间谓词、聚合(ST_Union_Agg、ST_Extent_Agg)、瓦片编码(ST_AsMVT)
|
|
37
|
+
- **与 Parquet/CSV/JSON 同库联查**:空间表可直接 JOIN 普通表,无须导入导出
|
|
38
|
+
- **WASM 可用**:同一扩展编译为 WebAssembly,GeoLibre 与 DuckDB-WASM 前端都靠它
|
|
39
|
+
|
|
40
|
+
扩展自带 GEOS/PROJ/GDAL 静态链接版本,机器上不需要另外安装 GDAL。
|
|
41
|
+
|
|
42
|
+
## 环境准备
|
|
43
|
+
|
|
44
|
+
### 安装 DuckDB
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# 1) Python(推荐用于脚本与 Notebook)
|
|
48
|
+
pip install duckdb==2.0.0
|
|
49
|
+
|
|
50
|
+
# 2) conda / mamba
|
|
51
|
+
conda install -c conda-forge duckdb
|
|
52
|
+
|
|
53
|
+
# 3) 官方 CLI(单文件可执行)
|
|
54
|
+
# Windows: 下载 duckdb_cli-windows-amd64.zip 后解压
|
|
55
|
+
# macOS: brew install duckdb
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 安装 spatial 扩展
|
|
59
|
+
|
|
60
|
+
```sql
|
|
61
|
+
INSTALL spatial;
|
|
62
|
+
LOAD spatial;
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
INSTALL 会把扩展写入用户目录(~/.duckdb/extensions/<version>/<platform>/),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时所有 ST_* 函数都会报"不存在"。
|
|
66
|
+
|
|
67
|
+
### 验证
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
import duckdb
|
|
71
|
+
con = duckdb.connect()
|
|
72
|
+
con.execute("INSTALL spatial; LOAD spatial;")
|
|
73
|
+
print(con.execute("SELECT duckdb_version()").fetchone())
|
|
74
|
+
print(con.execute("SELECT ST_AsText(ST_Point(116.39, 39.90))").fetchone())
|
|
75
|
+
print(con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name='spatial'").fetchone())
|
|
76
|
+
print(con.execute("SELECT duckdb_proj_version()").fetchone())
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
预期能打印 POINT (116.39 39.9) 与 PROJ 版本号;任一失败即扩展未正确加载。
|
|
80
|
+
|
|
81
|
+
## 核心 API
|
|
82
|
+
|
|
83
|
+
### 几何构造与序列化
|
|
84
|
+
|
|
85
|
+
| 函数 | 作用 | 返回 |
|
|
86
|
+
|------|------|------|
|
|
87
|
+
| ST_Point(x, y) / ST_MakePoint(x, y) | 构造点(两者等价,后者为 PostGIS 兼容名) | GEOMETRY |
|
|
88
|
+
| ST_GeomFromText(wkt [, ignore_invalid]) | 从 WKT 解析 | GEOMETRY |
|
|
89
|
+
| ST_GeomFromGeoJSON(json) / ST_AsGeoJSON(geom) | GeoJSON fragment 互转 | GEOMETRY / JSON |
|
|
90
|
+
| ST_GeomFromWKB(blob) / ST_AsWKB(geom) | WKB 互转 | GEOMETRY / WKB_BLOB |
|
|
91
|
+
| ST_MakeEnvelope(minx, miny, maxx, maxy) | 矩形面 | GEOMETRY |
|
|
92
|
+
| ST_MakeLine(list_of_points) / ST_MakePolygon(ring) | 线/面构造 | GEOMETRY |
|
|
93
|
+
| ST_AsText(geom) | 输出 WKT | VARCHAR |
|
|
94
|
+
|
|
95
|
+
```sql
|
|
96
|
+
SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
|
|
97
|
+
ST_AsText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY) AS poly,
|
|
98
|
+
ST_AsWKB('POINT(1 2)'::GEOMETRY)::BLOB AS wkb;
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。DuckDB Spatial 的 GEOMETRY 不保存 SRID,因此没有 ST_SetSRID 这类函数。
|
|
102
|
+
|
|
103
|
+
### 空间关系谓词
|
|
104
|
+
|
|
105
|
+
| 函数 | 说明 |
|
|
106
|
+
|------|------|
|
|
107
|
+
| ST_Intersects(a, b) | 相交(含接触) |
|
|
108
|
+
| ST_Contains(a, b) / ST_Within(a, b) | 包含 / 被包含 |
|
|
109
|
+
| ST_Covers(a, b) / ST_CoveredBy(a, b) | 覆盖(边界计入,比 Contains 宽松) |
|
|
110
|
+
| ST_Disjoint(a, b) | 不相交 |
|
|
111
|
+
| ST_Touches(a, b) / ST_Crosses(a, b) | 接触 / 穿越 |
|
|
112
|
+
| ST_DWithin(a, b, dist) | 距离小于阈值 |
|
|
113
|
+
| ST_Intersects_Extent(a, b) | 仅比较包围盒,最快的粗筛 |
|
|
114
|
+
|
|
115
|
+
```sql
|
|
116
|
+
-- 点落在面内:用 EXISTS 半连接,避免笛卡尔积
|
|
117
|
+
SELECT c.name
|
|
118
|
+
FROM cities c
|
|
119
|
+
WHERE EXISTS (
|
|
120
|
+
SELECT 1 FROM countries k
|
|
121
|
+
WHERE ST_Intersects(k.geom, c.geom)
|
|
122
|
+
);
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### 度量与构造
|
|
126
|
+
|
|
127
|
+
| 函数 | 说明 | 单位 |
|
|
128
|
+
|------|------|------|
|
|
129
|
+
| ST_Area(geom) | 平面面积(非面返回 0) | 与坐标系一致 |
|
|
130
|
+
| ST_Area_Spheroid(geom) | 椭球面积,假定输入为 EPSG:4326 | 平方米 |
|
|
131
|
+
| ST_Length(geom) | 平面长度 | 与坐标系一致 |
|
|
132
|
+
| ST_Length_Spheroid(geom) | 椭球长度 | 米 |
|
|
133
|
+
| ST_Distance(a, b) | 平面距离(忽略 Z) | 与坐标系一致 |
|
|
134
|
+
| ST_Distance_Sphere(a, b) | 大圆距离 | 米 |
|
|
135
|
+
| ST_Centroid(geom) | 质心 | GEOMETRY |
|
|
136
|
+
| ST_Buffer(geom, dist [, num_triangles]) | 缓冲,num_triangles 默认 8 | 与坐标系一致 |
|
|
137
|
+
| ST_Simplify / ST_SimplifyPreserveTopology | 简化 | — |
|
|
138
|
+
| ST_MakeValid / ST_IsValid | 修复 / 校验 | — |
|
|
139
|
+
|
|
140
|
+
```sql
|
|
141
|
+
-- 经纬度下 ST_Area 的单位是"平方度",要米制面积就用椭球版本
|
|
142
|
+
SELECT name,
|
|
143
|
+
ST_Area(geom) AS planar_deg2,
|
|
144
|
+
ST_Area_Spheroid(geom) AS spheroid_m2
|
|
145
|
+
FROM countries
|
|
146
|
+
ORDER BY spheroid_m2 DESC
|
|
147
|
+
LIMIT 5;
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### 坐标转换
|
|
151
|
+
|
|
152
|
+
```sql
|
|
153
|
+
-- 显式给出源与目标 CRS;always_xy 决定是否强制 x=经度
|
|
154
|
+
SELECT ST_AsText(
|
|
155
|
+
ST_Transform(ST_Point(116.39, 39.90), 'EPSG:4326', 'EPSG:3857')
|
|
156
|
+
);
|
|
157
|
+
|
|
158
|
+
-- 包围盒同样可以转换
|
|
159
|
+
SELECT ST_Transform({min_x: -180, min_y: -85, max_x: 180, max_y: 85}::BOX_2D,
|
|
160
|
+
'EPSG:4326', 'EPSG:3857');
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
CRS 字符串支持 PROJ 认得的写法('EPSG:4326'、'+proj=longlat +datum=WGS84'、WKT)。ST_Transform 不会替你猜坐标系,源 CRS 必须由你给出。
|
|
164
|
+
|
|
165
|
+
### 聚合与瓦片
|
|
166
|
+
|
|
167
|
+
| 函数 | 说明 |
|
|
168
|
+
|------|------|
|
|
169
|
+
| ST_Union_Agg(geom) | 合并要素(GEOS union) |
|
|
170
|
+
| ST_Extent_Agg(geom) | 最小包围盒多边形 |
|
|
171
|
+
| ST_Intersection_Agg(geom) | 批量求交 |
|
|
172
|
+
| ST_CoverageUnion_Agg(geom) | 覆盖合并(共享边界时更快) |
|
|
173
|
+
| ST_AsMVT(row, layer_name, extent, geom_col, id_col) | 生成 Mapbox Vector Tile |
|
|
174
|
+
| ST_AsMVTGeom(geom, bounds, extent, buffer, clip) | 裁剪到瓦片边界 |
|
|
175
|
+
|
|
176
|
+
```sql
|
|
177
|
+
-- 按省合并成一条 MultiPolygon,并给出总包围盒
|
|
178
|
+
SELECT province,
|
|
179
|
+
ST_AsText(ST_Union_Agg(geom)) AS merged,
|
|
180
|
+
ST_AsText(ST_Extent_Agg(geom)) AS bbox
|
|
181
|
+
FROM counties
|
|
182
|
+
GROUP BY province;
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### 文件读写(GDAL 表函数)
|
|
186
|
+
|
|
187
|
+
| 函数 | 说明 |
|
|
188
|
+
|------|------|
|
|
189
|
+
| ST_Read(path, ...) | 读矢量文件,参数见下表 |
|
|
190
|
+
| ST_Read_Meta(path) | 只读元数据(图层、CRS、字段) |
|
|
191
|
+
| ST_ReadSHP(path, encoding) | 不依赖 GDAL 的 Shapefile 读取(快,基础类型) |
|
|
192
|
+
| ST_ReadOSM(path) | 直接解析 .osm.pbf,输出原始 Nodes/Ways/Relations |
|
|
193
|
+
| ST_Drivers() | 列出编译进来的 GDAL 驱动 |
|
|
194
|
+
|
|
195
|
+
常用 ST_Read 参数:
|
|
196
|
+
|
|
197
|
+
| 参数 | 类型 | 说明 |
|
|
198
|
+
|------|------|------|
|
|
199
|
+
| layer | VARCHAR | 图层名或索引(0 起);多图层文件必给 |
|
|
200
|
+
| spatial_filter_box | BOX_2D | 按包围盒过滤(部分驱动可下推) |
|
|
201
|
+
| spatial_filter | WKB_BLOB | 按任意几何过滤 |
|
|
202
|
+
| open_options | VARCHAR[] | 透传 GDAL 打开选项,如 FLATTEN_NESTED_ATTRIBUTES=YES |
|
|
203
|
+
| allowed_drivers | VARCHAR[] | 限制可用驱动 |
|
|
204
|
+
| keep_wkb | BOOLEAN | 返回 wkb_geometry(WKB_BLOB)而非 GEOMETRY |
|
|
205
|
+
|
|
206
|
+
```sql
|
|
207
|
+
-- 单图层文件
|
|
208
|
+
CREATE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');
|
|
209
|
+
|
|
210
|
+
-- 指定图层 + 包围盒过滤
|
|
211
|
+
SELECT * FROM ST_Read('data/city.gpkg',
|
|
212
|
+
layer := 'buildings',
|
|
213
|
+
spatial_filter_box := {min_x: 116.0, min_y: 39.5,
|
|
214
|
+
max_x: 116.6, max_y: 40.1}::BOX_2D);
|
|
215
|
+
|
|
216
|
+
-- 先看元数据,再决定读哪个图层
|
|
217
|
+
SELECT unnest(layers).name FROM ST_Read_Meta('data/city.gpkg');
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
替换扫描(replacement scan):.shp、.gpkg、.fgb 三种扩展名可以直接当表名查,无需 ST_Read:
|
|
221
|
+
|
|
222
|
+
```sql
|
|
223
|
+
SELECT * FROM 'data/roads.shp' LIMIT 5;
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
这只是 ST_Read 的语法糖,性能一致;要传参数时仍应显式调用 ST_Read。
|
|
227
|
+
|
|
228
|
+
## 典型工作流:Shapefile → 空间分析 → GeoParquet
|
|
229
|
+
|
|
230
|
+
输入 data/roads.shp(线)与 data/districts.shp(面),目标是从每条道路提取落在各区的长度并输出 Parquet。
|
|
231
|
+
|
|
232
|
+
```python
|
|
233
|
+
import duckdb
|
|
234
|
+
|
|
235
|
+
con = duckdb.connect("analysis.duckdb")
|
|
236
|
+
con.execute("INSTALL spatial; LOAD spatial;")
|
|
237
|
+
|
|
238
|
+
# 1) 读入并落到持久表(避免每次查询重复解析 Shapefile)
|
|
239
|
+
con.execute("CREATE OR REPLACE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');")
|
|
240
|
+
con.execute("CREATE OR REPLACE TABLE districts AS SELECT * FROM ST_Read('data/districts.shp');")
|
|
241
|
+
|
|
242
|
+
# 2) 探明列名与 CRS
|
|
243
|
+
print(con.execute("DESCRIBE roads").fetchall())
|
|
244
|
+
print(con.execute("""
|
|
245
|
+
SELECT layers[1].geometry_fields[1].crs.auth_name,
|
|
246
|
+
layers[1].geometry_fields[1].crs.auth_code
|
|
247
|
+
FROM ST_Read_Meta('data/roads.shp')
|
|
248
|
+
""").fetchone())
|
|
249
|
+
|
|
250
|
+
# 3) 统一到投影坐标系后再算长度(米),避免把"度"当"米"
|
|
251
|
+
con.execute("""
|
|
252
|
+
CREATE OR REPLACE TABLE roads_m AS
|
|
253
|
+
SELECT *, ST_Transform(geom, 'EPSG:4326', 'EPSG:3857') AS geom_m,
|
|
254
|
+
ST_Length(ST_Transform(geom, 'EPSG:4326', 'EPSG:3857')) AS length_m
|
|
255
|
+
FROM roads;
|
|
256
|
+
""")
|
|
257
|
+
con.execute("""
|
|
258
|
+
CREATE OR REPLACE TABLE districts_m AS
|
|
259
|
+
SELECT *, ST_Transform(geom, 'EPSG:4326', 'EPSG:3857') AS geom_m
|
|
260
|
+
FROM districts;
|
|
261
|
+
""")
|
|
262
|
+
|
|
263
|
+
# 4) 叠加:相交取交线,按区汇总长度
|
|
264
|
+
con.execute("""
|
|
265
|
+
CREATE OR REPLACE TABLE road_length_by_district AS
|
|
266
|
+
SELECT d.name AS district,
|
|
267
|
+
SUM(ST_Length(ST_Intersection(r.geom_m, d.geom_m))) AS length_m
|
|
268
|
+
FROM roads_m r
|
|
269
|
+
JOIN districts_m d
|
|
270
|
+
ON ST_Intersects(r.geom_m, d.geom_m)
|
|
271
|
+
GROUP BY d.name
|
|
272
|
+
ORDER BY length_m DESC;
|
|
273
|
+
""")
|
|
274
|
+
|
|
275
|
+
# 5) 输出:几何列写成 WKB
|
|
276
|
+
con.execute("""
|
|
277
|
+
COPY (SELECT ST_AsWKB(geom_m) AS geometry, name, length_m FROM roads_m)
|
|
278
|
+
TO 'out/roads_m.parquet' (FORMAT parquet);
|
|
279
|
+
""")
|
|
280
|
+
|
|
281
|
+
print(con.execute("SELECT * FROM road_length_by_district LIMIT 10").fetchall())
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
输出 out/roads_m.parquet 与一张按区汇总的长度表。要点:先把 Shapefile 落到持久表(重复 ST_Read 很慢)、先投影再算长度、按区名分组而不是逐行比较。
|
|
285
|
+
|
|
286
|
+
## 与 Python / pandas 协作
|
|
287
|
+
|
|
288
|
+
```python
|
|
289
|
+
import duckdb, geopandas as gpd
|
|
290
|
+
|
|
291
|
+
con = duckdb.connect()
|
|
292
|
+
con.execute("INSTALL spatial; LOAD spatial;")
|
|
293
|
+
|
|
294
|
+
# 查询结果直接转 DataFrame
|
|
295
|
+
rows = con.execute("SELECT name, ST_AsText(geom) FROM ST_Read('data/cities.shp')").fetchdf()
|
|
296
|
+
|
|
297
|
+
# GeoDataFrame 注册成视图后即可用 SQL 查询
|
|
298
|
+
districts = gpd.read_file("data/districts.gpkg")
|
|
299
|
+
con.register("districts", districts)
|
|
300
|
+
print(con.execute("SELECT name, ST_Area(geom) AS area FROM districts ORDER BY area DESC LIMIT 5").fetchall())
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
register 只在当前会话有效;跨进程请建表或直接读文件。
|
|
304
|
+
|
|
305
|
+
## 输出 GeoParquet 与矢量瓦片
|
|
306
|
+
|
|
307
|
+
```sql
|
|
308
|
+
-- GeoParquet:几何列写成 WKB,字段名用 geometry 便于下游识别
|
|
309
|
+
COPY (SELECT ST_AsWKB(geom) AS geometry, name, pop FROM cities)
|
|
310
|
+
TO 'out/cities.parquet' (FORMAT parquet);
|
|
311
|
+
|
|
312
|
+
-- MVT:先裁剪到瓦片,再聚合
|
|
313
|
+
WITH tile AS (
|
|
314
|
+
SELECT ST_AsMVTGeom(
|
|
315
|
+
ST_Transform(geom, 'EPSG:4326', 'EPSG:3857'),
|
|
316
|
+
ST_TileEnvelope(12, 3423, 1586)
|
|
317
|
+
) AS geom,
|
|
318
|
+
name
|
|
319
|
+
FROM cities
|
|
320
|
+
WHERE ST_Intersects_Extent(
|
|
321
|
+
ST_Transform(geom, 'EPSG:4326', 'EPSG:3857'),
|
|
322
|
+
ST_TileEnvelope(12, 3423, 1586))
|
|
323
|
+
)
|
|
324
|
+
SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
## 性能优化
|
|
328
|
+
|
|
329
|
+
1. **落表再查**:对同一文件重复 ST_Read 会反复走 GDAL 解析,先 CREATE TABLE AS 物化。GDAL 是单线程的,ST_Read 无法并行。
|
|
330
|
+
2. **没有空间索引,先做包围盒粗筛**:DuckDB Spatial 不提供 R-Tree 索引,join 前用 ST_Intersects_Extent 缩小候选集,再用 ST_Intersects 精确判断。
|
|
331
|
+
3. **优先用轻量类型**:能落成 POINT_2D / POLYGON_2D 的列走原生实现,必要时用 ST_Force2D 去掉 Z/M。
|
|
332
|
+
4. **面积/长度单位要有依据**:经纬度下 ST_Area 的单位是平方度,应改用 ST_Area_Spheroid 或先投影。
|
|
333
|
+
5. **投影一次即可**:ST_Transform 是 CPU 热点,放在建表阶段,不要写在 WHERE 里逐行算。
|
|
334
|
+
6. **减少字符串往返**:几何尽量保持二进制形态,只在最终输出时 ST_AsText / ST_AsWKB。
|
|
335
|
+
7. **大文件用列裁剪**:SELECT name, geom 比 SELECT * 少读属性列。
|
|
336
|
+
|
|
337
|
+
## 常见问题
|
|
338
|
+
|
|
339
|
+
| 问题 | 原因 | 解决方案 |
|
|
340
|
+
|------|------|---------|
|
|
341
|
+
| Extension spatial is not installed | 只写了 LOAD 没写 INSTALL,或离线环境拉不到扩展 | 先执行 INSTALL spatial;离线时复用扩展目录,或下载官方 unsigned 构建后 INSTALL '<path>'(需 -unsigned 启动) |
|
|
342
|
+
| Catalog Error: Scalar Function with name ST_Intersects does not exist | 当前连接没 LOAD spatial | 每个新连接都要 LOAD spatial;Python 里可在建连后立即执行 |
|
|
343
|
+
| ST_Area 返回 0 或很小的数 | 输入是经纬度,单位是平方度 | 用 ST_Area_Spheroid,或先 ST_Transform 到米制投影 |
|
|
344
|
+
| ST_Transform 报 CRS 解析失败 | 源/目标 CRS 字符串拼错或 PROJ 未识别 | 用 'EPSG:4326' 这类标准写法;SELECT duckdb_proj_version() 确认 PROJ 可用 |
|
|
345
|
+
| 读 GeoPackage 只拿到第一个图层 | 多图层文件未指定 layer | 用 ST_Read_Meta 先看 layers,再 ST_Read(..., layer := '...') |
|
|
346
|
+
| Shapefile 中文属性乱码 | DBF 编码与默认 UTF-8 不一致 | 用 ST_ReadSHP(path, encoding := 'GBK'),或在 open_options 里给驱动指定编码 |
|
|
347
|
+
| 空间 join 极慢 | 没有空间索引,也没做包围盒粗筛 | 先 ST_Intersects_Extent 粗筛,再 ST_Intersects 精筛 |
|
|
348
|
+
| 写出的 Parquet 没有 CRS | ST_AsWKB 只写几何,不写 CRS 元数据 | 落盘后用 GeoPandas/GDAL 补写 crs,或用 ogr2ogr 转出 |
|
|
349
|
+
| ST_ReadOSM 只返回 node/way 原始表 | 该函数不做几何装配 | 需要成品几何时改用 ST_Read 的 OSM 驱动 |
|
|
350
|
+
|
|
351
|
+
## AI 使用建议
|
|
352
|
+
|
|
353
|
+
- **先验扩展再写 SQL**:执行前跑 SELECT extension_name, loaded FROM duckdb_extensions() WHERE extension_name='spatial'; 确认 loaded=true;未加载就先 LOAD,不要把"函数不存在"当语法错误去改。
|
|
354
|
+
- **版本敏感**:2.0.0 与旧版函数集合有差异(ST_Area_Spheroid、ST_CoverageUnion_Agg 属较新函数)。写示例前用 SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'; 探测实际可用函数。
|
|
355
|
+
- **大文件不要整读进内存**:优先用 ST_Read 的 spatial_filter_box / layer 参数与 Parquet 列裁剪;反复查询时先落表。
|
|
356
|
+
- **验证产物**:写完 Parquet/MVT 后回读核对 count、ST_IsValid、ST_GeometryType 分布,以及坐标范围是否落在预期 CRS 内。
|
|
357
|
+
- **写操作确认**:COPY ... TO、CREATE OR REPLACE TABLE、DROP TABLE 会覆盖文件或表;执行前确认目标路径已被授权覆盖。
|
|
358
|
+
|
|
359
|
+
## 相关技能
|
|
360
|
+
|
|
361
|
+
- **postgis** — 服务端空间数据库,DuckDB 的常见替代:[../postgis/SKILL.md](../postgis/SKILL.md)
|
|
362
|
+
- **geopandas** — Python 矢量分析,可与 DuckDB 互转:[../geopandas/SKILL.md](../geopandas/SKILL.md)
|
|
363
|
+
- **gdal** — ST_Read 背后的读写引擎与格式转换:[../gdal/SKILL.md](../gdal/SKILL.md)
|
|
364
|
+
- **proj** — CRS 定义与 ST_Transform 的底层库:[../proj/SKILL.md](../proj/SKILL.md)
|
|
365
|
+
- **geolibre** — 浏览器里用 DuckDB-WASM Spatial 做 SQL 分析:[../geolibre/SKILL.md](../geolibre/SKILL.md)
|
|
366
|
+
|
|
367
|
+
## 参考资源
|
|
368
|
+
- 扩展仓库:<https://github.com/duckdb/duckdb-spatial>
|
|
369
|
+
- 函数总表:<https://duckdb.org/docs/stable/core_extensions/spatial/functions>
|
|
370
|
+
- DuckDB 文档:<https://duckdb.org/docs/stable/>
|