DuckDB 教程

DuckDB 简介与安装 本节目标 读完本篇，你应能： 安装 DuckDB CLI（Command Line Interface，命令行客户端），并确认版本 用 duckdb 打开内存库 (in-memory database)，用 duckdb my.db 创建或打开持久化库 (persistent database) 在 CLI 中使用 .help、.open 等 dot 命令，并正常退出 跑通一条 SELECT，理解结果在终端中的展示方式 DuckDB 是什么 DuckDB 是一款嵌入式分析型数据库 (embedded analytical database)：引擎以库的形式跑在你的进程内 (in-process)，而不是独立的服务端进程。它面向 OLAP (Online Analytical Processing，联机分析处理) 场景——聚合、扫描、列式分析——而不是高并发小事务的 OLTP。 常见用法包括：本地/笔记本上的数据分析、ETL 管道中的轻量 SQL 引擎、在 Python/R/Go 等语言里直接 import 后执行 SQL。单文件持久化库（如 my.db、*.duckdb）便于拷贝与版本管理；不写路径时则使用临时内存库，进程结束即丢失（除非你先 .open 或导出）。 自 v0.10 起，存储格式在版本间向后兼容；内存与持久化模式在数据大于内存时都可以溢出到磁盘 (spill to disk)。更多连接语义见官方 Connect Overview。 安装 CLI DuckDB CLI 是单个、无额外依赖的可执行文件，官方为 Windows、macOS、Linux 提供预编译包。各平台最新包与版本选项以安装页为准： DuckDB Installation（选择 Command line 与对应 Platform） macOS（Homebrew） 在 macOS 上，Homebrew 提供稳定包（安装页当前列出的方式之一）： ...

SQL 基础 本节目标 读完本篇，你应能： 用 CREATE TABLE 定义表结构，并用 INSERT INTO 写入行 编写 SELECT 查询，配合 WHERE 过滤、ORDER BY 排序、LIMIT 限制行数 使用 GROUP BY 与聚合函数做汇总统计 识别 DuckDB Friendly SQL 中两种常用写法：FROM 在前（等价于 SELECT *）与 CREATE TABLE ... AS SELECT（CTAS） 避开标识符大小写与字符串引号等常见方言差异 若尚未安装 CLI 或连接内存库/文件库，请先阅读 简介与安装。 概念：DuckDB 里的 SQL 长什么样 DuckDB 的 SQL 方言 (dialect) 整体接近 PostgreSQL，而不是 SQLite：类型系统、函数与不少语法与 PG 更一致。你在 CLI 或 Python 里执行的语句，会先被解析成逻辑计划，再在列式引擎上执行——本篇只关心声明式查询怎么写，不涉及执行计划。 一条典型查询的执行顺序在逻辑上是：FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT。写 SQL 时顺序可以不同，但理解这个顺序有助于读懂聚合与过滤为何这样组合。 ...

SQL 进阶 本节目标 读完本篇，你应能： 用 INNER JOIN 与 LEFT JOIN 关联多张表，并理解「保留哪一侧行」的差异 用 WITH（CTE，Common Table Expression）拆分复杂查询、提高可读性 编写窗口函数：按分区排序编号（ROW_NUMBER）与累计求和（SUM() OVER） 各写一条 PIVOT 与 UNPIVOT 示例，理解宽表与长表互转 用 CREATE VIEW 封装常用查询，用 CREATE MACRO 定义可复用的 SQL 表达式 区分窗口函数与聚合函数，并知道 DuckDB 的 QUALIFY 如何过滤窗口结果 若还不熟悉 SELECT / GROUP BY，请先阅读 SQL 基础。 概念：从单表到多表与「不折叠行」的汇总 SQL 基础 里主要在一张 employees 表上做单表查询与 GROUP BY 聚合。进阶查询常见两类需求： 多表关联：例如部门详情在另一张表，需要把员工与部门信息拼在同一结果里。 保留明细行的统计：聚合会把多行压成一行；窗口函数 (window functions) 在「当前结果集的每一行」上再算一列（如组内排名、累计和），行数不变。 下面仍从 employees 出发，并增加 departments 与一张用于透视的 sales 表。建议在 CLI 中按块复制执行。 准备示例数据 CREATE OR REPLACE TABLE employees ( id INTEGER PRIMARY KEY, name VARCHAR, department_id INTEGER, salary DOUBLE ); CREATE OR REPLACE TABLE departments ( id INTEGER PRIMARY KEY, name VARCHAR, location VARCHAR ); INSERT INTO employees VALUES (1, 'Alice', 10, 120000), (2, 'Bob', 10, 95000), (3, 'Carol', 20, 88000), (4, 'Dave', 20, 91000), (5, 'Eve', 10, 105000), (6, 'Frank', NULL, 72000); INSERT INTO departments VALUES (10, 'Engineering', 'Building A'), (20, 'Sales', 'Building B'); CREATE OR REPLACE TABLE sales ( region VARCHAR, product VARCHAR, amount DOUBLE ); INSERT INTO sales VALUES ('East', 'Widget', 100), ('East', 'Gadget', 80), ('West', 'Widget', 120), ('West', 'Gadget', 90); Frank 的 department_id 为 NULL，便于演示 LEFT JOIN 与内连接结果差异。 ...

类型与函数 本节目标 读完本篇，你应能： 选用常见的标量类型 (scalar types)：数值、文本、布尔、日期与时间 创建并查询 LIST、STRUCT、MAP 等嵌套类型，并用 UNNEST 展开列表 使用字符串、日期时间与聚合方面的常用函数 用 CAST / TRY_CAST 做显式类型转换，并理解失败时的差异 避开 NULL 三值逻辑、TIMESTAMP 与时区、嵌套列访问等常见误区 若还不熟悉 JOIN、窗口函数等，请先阅读 SQL 进阶。 概念：类型决定能算什么 DuckDB 的类型系统整体接近 PostgreSQL，而不是 SQLite：整数有 INTEGER / BIGINT / HUGEINT，浮点有 FLOAT / DOUBLE，还有 DECIMAL(p, s) 固定精度小数。列式引擎会在执行前推断或校验类型；写错类型（例如把字符串当日期做减法）往往在解析或运行阶段就会报错。 除标量外，DuckDB 还提供 LIST（变长同类型数组）、STRUCT（固定键名的嵌套行）、MAP（键值对，各行键可不同）等嵌套类型，便于在单表里存 JSON 式或半结构化数据，而不必先拆成多张规范化表。 下面示例建议在 CLI 中按块复制执行。 标量类型：数值、文本、布尔、日期时间 数值：日常计数用 INTEGER；金额、科学计数可用 DOUBLE 或 DECIMAL(18, 2) 控制小数位。 SELECT 42::INTEGER AS n, 3.14::DOUBLE AS approx, 1234.56::DECIMAL(10, 2) AS money; :: 是 PostgreSQL 风格的类型后缀，等价于 CAST(expr AS type)。 ...

导入与导出 本节目标 读完本篇，你应能： 用 read_csv、路径字面量或 COPY ... FROM 读入 CSV，并在需要时显式指定分隔符、表头与列类型 用 read_parquet（或 '*.parquet' 路径）读 Parquet，并用 DESCRIBE 查看列类型 用 read_json / read_json_auto 把 JSON 读成表，或用 COPY ... FROM 导入 JSON 用 COPY ... TO 把查询结果或表导出为 CSV、Parquet、JSON 用 glob 通配符一次读多个同类型文件，并了解 Hive 分区目录的读写法 避开 auto-detect 类型推断、编码、大文件内存 等常见误区 若还不熟悉 CAST / TRY_CAST 与嵌套类型，请先阅读 类型与函数。 概念：文件即表 DuckDB 把磁盘上的数据文件当作外部表 (external table)：在 SELECT 里写文件路径，引擎按需扫描，不必先把整文件导入数据库。路径相对于当前工作目录（CLI 启动时的目录）；示例里用占位路径如 'data/flights.csv'，你需要在本地准备同名文件或改成自己的路径。 两种等价风格很常见： 风格 示例 适用 路径字面量 SELECT * FROM 'data/flights.csv' 扩展名明确、选项可自动推断 读函数 read_csv('data/flights.csv', ...) 需要显式选项或非标准扩展名 持久化到 .duckdb 里用 CREATE TABLE ... AS SELECT 或 COPY table FROM 'file'，适合反复查询同一批数据。 ...

Python 客户端 本节目标 读完本篇，你应能： 用 pip install duckdb 安装官方 Python 包，并创建 duckdb.connect() 连接（内存库或文件库） 用 execute / sql 跑 SQL，并用 fetchdf()（或 df()）把结果取成 Pandas DataFrame 在 SQL 中直接引用 DataFrame 变量，或把查询结果写回 Pandas 了解 Apache Arrow 零拷贝互操作的入口（fetch_arrow_table / arrow()） 用 Relational API 链式构造查询，并理解惰性求值 避开 连接生命周期、默认连接与多线程使用上的常见误区 若还不熟悉从磁盘读 CSV/Parquet，请先阅读 导入与导出。 安装与环境 DuckDB Python 包可通过 pip 安装（Python 3.10+）： pip install duckdb Conda 用户也可使用 conda install python-duckdb -c conda-forge。CLI、Python 包与扩展版本建议对齐同一主版本线，避免存储格式或符号不兼容（见 简介与安装 中的版本说明）。 连接：duckdb.connect() duckdb.connect 返回符合 PEP 249 DB-API 的 DuckDBPyConnection，语义类似 Python 标准库里的 sqlite3。 ...

常用扩展 本节目标 读完本篇，你应能： 用 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，行为一致。 ...

性能与运维 本节目标 读完本篇，你应能： 用 EXPLAIN 查看物理执行计划，用 EXPLAIN ANALYZE 在真实执行中拿到各算子耗时与基数 通过 SET 调整 memory_limit、threads、temp_directory 等官方配置项，理解内存与并行对分析负载的影响 知道 Min-Max（zonemap） 与 ART 索引各自适用场景，避免误建大 ART 索引 掌握扩展来源、不可信 SQL 与嵌入 (embedding) 场景下的基本安全思路 按清单排查 OOM（内存耗尽） 与慢查询常见问题 若尚未熟悉远程读与扩展加载，请先阅读 常用扩展。全系列索引见 DuckDB 教程。 性能调优总览 DuckDB 默认配置已针对分析型负载做了较多优化；多数场景下先写清晰 SQL、选对文件格式（如 Parquet），再按需微调内存与线程即可。官方 Performance Guide 按导入、连接、Join、索引等主题展开；本篇聚焦日常运维与排错入口。 EXPLAIN：查看查询计划 在任意查询前加上 EXPLAIN，会输出即将执行的物理计划 (physical plan)——一棵按顺序执行的算子树。优化器会在合法范围内改写计划以降低成本。 CREATE TABLE students (name VARCHAR, sid INTEGER); CREATE TABLE exams (eid INTEGER, subject VARCHAR, sid INTEGER); EXPLAIN SELECT name FROM students JOIN exams USING (sid) WHERE name LIKE 'Ma%'; 阅读计划时可关注：扫描方式（全表 vs 过滤后）、Join 顺序与类型、是否出现 Hash Aggregate 等。计划文本较长时，可配合官方 EXPLAIN 指南 对照算子含义。 ...

Go 客户端 本节目标 读完本篇，你应能： 用 go get github.com/duckdb/duckdb-go/v2 引入官方 Go 驱动，并理解 cgo 与预编译 DuckDB 库的关系 通过标准库 database/sql 打开内存库 / 文件库，配置 DSN，正确 Close 用 ExecContext / QueryContext、占位符与事务完成 CRUD 用 Appender 做大批量行插入；用 duckdb.Composite 扫描 LIST / STRUCT / JSON 注册简单的 标量 UDF，并按 duckdb.Error.Type 分类处理错误 避开连接池、临时表、并发与 Windows/交叉编译等常见坑 若还不熟悉 DuckDB SQL 与导入导出，建议先读 SQL 基础 与 导入与导出。本篇 API 以 Go Client 官方文档 为准。 概念：为何选 Go 客户端 官方 Go 客户端 duckdb-go 是符合 Go database/sql 的 SQL 驱动。业务代码用与 PostgreSQL、SQLite 相同的 *sql.DB / Query / Scan 习惯即可嵌入 DuckDB。 ...