常用扩展

本节目标

读完本篇，你应能：

用 INSTALL / LOAD 安装并加载扩展，并用 duckdb_extensions() 查看已装扩展
理解 autoload（自动加载） 与需手动 LOAD 的扩展（如 spatial）的区别
用 httpfs 从 HTTP(S) 或 S3 路径读远程文件，并理解 CREATE SECRET 如何集中管理云凭证（示例中只用占位符，勿写真实密钥）
了解 excel 扩展读写 .xlsx 的入口
用 spatial 跑一条最简单的几何示例
知道 iceberg / delta 扩展在「能读表、知配置方向」层面的用法边界（非生产运维手册）
避开 扩展版本与 DuckDB 主版本不匹配 等常见坑

若还不熟悉本地 CSV/Parquet 路径读法，请先阅读导入与导出。在 Python 里加载扩展的方式与 CLI 相同 SQL，见 Python 客户端。

扩展机制概览

DuckDB 通过扩展 (extension) 动态增加能力：新文件格式、新类型、远程 I/O、湖仓表格式等。官方 core 仓库（默认 extensions.duckdb.org）提供经团队构建与签名的核心扩展；也可从其它仓库（如 core_nightly）安装，但稳定性与版本对齐需自行评估。

查看当前环境可用扩展及是否已安装：

SELECT extension_name, installed, description
FROM duckdb_extensions()
ORDER BY extension_name;

扩展在 CLI、Python、R 等客户端上均可 INSTALL / LOAD，行为一致。

INSTALL 与 LOAD

命令	作用
`INSTALL 扩展名`	把扩展二进制下载到本地扩展目录（默认来自 core 仓库）
`LOAD 扩展名`	在当前 DuckDB 实例中加载已安装的扩展，使其函数与文件系统生效

典型手动流程（以远程文件扩展为例）：

INSTALL httpfs;
LOAD httpfs;

部分扩展在首次用到相关功能时会 autoload（自动安装/加载），例如 httpfs、excel、delta 等。另一些扩展不会 autoload，必须先 LOAD，否则调用会报错——spatial 即属此类：

INSTALL spatial;
LOAD spatial;

习惯上：脚本里若依赖某扩展，显式 INSTALL + LOAD 更可重复；交互式探索时可依赖 autoload，但生产或 CI 建议写死加载步骤。

从非默认仓库安装（仅作了解，日常用 core 即可）：

-- 示例：从 nightly 仓库安装（版本需与 DuckDB 匹配）
INSTALL httpfs FROM core_nightly;

httpfs：HTTP(S) 与 S3

httpfs 注册一套远程文件系统：让 read_csv、read_parquet 等函数的路径参数可以是 URL 或 S3 风格 URI。

HTTP(S)（通常只读）

安装并加载后，可直接用 HTTPS URL 扫描（需网络可达）：

INSTALL httpfs;
LOAD httpfs;

SELECT *
FROM read_csv('https://example.com/data/sample.csv');
-- 或
SELECT count(*) FROM read_parquet('https://example.com/data/sample.parquet');

纯 HTTP(S) 场景一般不支持写回远程端；对象存储（S3 API）才常见读写与 glob。

S3 与 SECRET 概念

访问 S3（及兼容 S3 API 的对象存储）时，客户端需要区域、访问密钥或临时凭证等。DuckDB 用 CREATE SECRET 把这类配置登记在 catalog 里，供 httpfs 在解析 s3://bucket/key 时查找——避免在每条 SQL 里重复写密钥，也便于用 DROP SECRET / 作用域管理轮换凭证。

下面仅为语法示意，请将占位符换成你自己的配置方式（环境变量、IAM 角色、密钥管理服务等），不要在文档、笔记本或版本库中粘贴真实 Access Key：

INSTALL httpfs;
LOAD httpfs;

CREATE SECRET s3_demo (
    TYPE s3,
    KEY_ID 'YOUR_ACCESS_KEY_ID',
    SECRET 'YOUR_SECRET_ACCESS_KEY',
    REGION 'ap-southeast-1'
);

SELECT *
FROM read_parquet('s3://your-bucket/path/data/*.parquet');

说明要点：

TYPE s3 表示 S3 兼容存储；不同云厂商可能有专用 SECRET 类型或额外参数，以 httpfs 官方文档为准。
也可通过环境变量或实例 settings 提供凭证，具体选项见官方「S3 / Secrets」章节。
路径支持 glob（如 *.parquet），与本地多文件读法类似（见导入与导出）。

远程读大文件时，仍须关注网络超时、带宽与重试；这与本地磁盘 I/O 的调优不同，本篇不展开运维细节。

Excel：读写 `.xlsx` 简述

excel 扩展支持 Excel 2007+ 的 .xlsx（不支持旧版 .xls）。可 autoload；手动加载：

INSTALL excel;
LOAD excel;

读表常用 read_xlsx（表名、范围等参数见官方文档）：

SELECT * FROM read_xlsx('reports/summary.xlsx', sheet => 'Sheet1');

导出可在 COPY ... TO 中指定 Excel 相关格式，或使用扩展提供的写函数；数字展示还可使用标量函数 excel_text(number, format_string)（别名 text(...)），按 Excel 格式规则格式化数字。

Spatial：一句示例级入门

spatial 为 DuckDB 增加 GEOMETRY 等地理空间类型与 OGC 风格函数（点、线、面、距离、谓词等）。安装后必须 LOAD spatial。

最小示例：两点欧氏距离（具体函数集以官方 spatial 文档为准）：

INSTALL spatial;
LOAD spatial;

SELECT ST_Distance(
    ST_Point(0.0, 0.0),
    ST_Point(3.0, 4.0)
) AS distance;
-- 期望结果约为 5.0

真实项目里还会涉及 WKT/WKB 导入、坐标参考系 (CRS)、空间索引 等；本篇只建立「装扩展 → LOAD → 调 ST_ 函数」的路径。

Iceberg 与 Delta：入门级

二者都是开放表格式 (open table format)，在 Parquet 等文件之上增加元数据层（快照、模式演进、分区统计等）。DuckDB 通过独立扩展接入，读本地或远程表的入门路径如下；写表、REST Catalog、分区策略等属于进阶主题，请参阅官方专章。

Apache Iceberg（`iceberg` 扩展）

支持两类方式（知道存在即可）：

单表只读：指向表的 metadata 路径，无需挂载 catalog。
Catalog 管理：ATTACH Iceberg REST Catalog 等，功能更完整（含写入等）。

手动加载：

INSTALL iceberg;
LOAD iceberg;

只读扫描表示例（路径请换成你的 metadata 文件或表根目录，语法以当前版本文档为准）：

SELECT *
FROM iceberg_scan('warehouse/db/table/metadata/00000-xxx.metadata.json');

若团队使用 REST Catalog，配置连接串、SECRET 与 ATTACH 选项即可在 DuckDB 里当数据库用；细节见 Iceberg 扩展文档。

Delta Lake（`delta` 扩展）

delta 扩展基于 Delta Kernel，对 Delta 表提供读/写能力（本地路径或远程）。可 autoload：

INSTALL delta;
LOAD delta;

SELECT *
FROM delta_scan('path/to/delta_table');
-- 远程示例：delta_scan('s3://bucket/delta_table/') 需 httpfs + 相应 SECRET

Unity Catalog 等场景可能有 unity_catalog 等配套扩展；与 Azure OneLake 相关的已知回归问题请查阅官方 issue，升级前先在测试环境验证。

常见坑

扩展版本与 DuckDB 版本不匹配：扩展二进制按 DuckDB 主版本 构建。升级 DuckDB 后若出现「无法加载扩展」「符号未找到」或莫名崩溃，先 INSTALL 扩展名 重装 core 仓库扩展，并保证 CLI、Python 包、扩展来自同一发行线（见简介与安装）。
只 INSTALL 不 LOAD：非 autoload 扩展（如 spatial）未 LOAD 就调用函数，会报扩展未加载。
混用 nightly 与 stable：从 core_nightly 装的扩展与稳定版 DuckDB 组合可能不稳定；教学与生产默认用 core + 同版本 DuckDB。
S3 凭证与 SECRET 作用域：SECRET 名冲突、过期临时凭证未更新、或 REGION 与 bucket 不一致会导致 403；用占位符调试时先确认 URI 与权限策略，勿把密钥写进 SQL 文件。
远程读当本地读：HTTP/S3 失败时检查 LOAD httpfs、网络代理、以及路径是否需 URL 编码；大目录 glob 可能触发大量 LIST/GET，成本与超时与本地不同。
Iceberg/Delta 路径不是「单个 Parquet 文件」：应对准 metadata / 表目录，否则扫描报错或空结果；版本升级后函数名或参数可能有变，以 current 文档为准。

常用扩展#

本节目标#

扩展机制概览#

INSTALL 与 LOAD#

httpfs：HTTP(S) 与 S3#

HTTP(S)（通常只读）#

S3 与 SECRET 概念#

Excel：读写 .xlsx 简述#

Spatial：一句示例级入门#

Iceberg 与 Delta：入门级#

Apache Iceberg（iceberg 扩展）#

Delta Lake（delta 扩展）#

常见坑#

延伸阅读#