DuckDB 1.5 深度拆解：当「分析界的 SQLite」装上 VARIANT 与 Vortex 引擎——从进程内向量化执行到 Lakehouse 实战的工程全貌（2026）

关键词：DuckDB、进程内 OLAP、向量化执行、VARIANT 类型、Vortex 存储引擎、Iceberg、湖仓一体、数据工程

如果你是一个后端或数据工程师，大概率经历过这样的场景：手上有一堆几个 GB 的 Parquet/CSV 文件，只想跑一条 GROUP BY 看看分布，却不得不为了这点事拉起一个 Spark 集群，或者把数据塞进 Pandas 然后眼睁睁看着内存爆掉。这种「杀鸡用牛刀」的痛苦，正是 DuckDB 想要消灭的。

2026 年，DuckDB 1.5.0（代号 Variegata，灵感来自新西兰特有的天堂鸭）正式发布，带来了翻新后的命令行客户端、原生 VARIANT 类型、内置 GEOMETRY 空间类型、非阻塞检查点（non-blocking checkpoint）等一系列重磅特性。而在 1.4.x 系列中，DuckDB 还悄悄放出了 Vortex 存储引擎和完整的 Iceberg DML 能力。这一年，DuckDB 正在从「SQLite 的分析平替」一步步进化成「进程内的湖仓引擎」。

本文将从工程师视角，把 DuckDB 1.5 拆开揉碎：它的进程内架构为什么能比 Pandas 快一个数量级？向量化执行引擎的底层数据块（Data Chunk）到底长什么样？VARIANT 类型解决了什么历史遗留痛点？Vortex 引擎和 Iceberg DML 又意味着什么？最后用一套可运行的代码实战，让你今天就能把 DuckDB 落到生产。

一、背景：为什么我们需要一个「分析界的 SQLite」

1.1 客户端-服务器数据库的错位

传统 OLAP 数据库（ClickHouse、Greenplum、Snowflake）的设计哲学是：独立服务进程 + 网络协议 + 分布式存储。这套体系应对 TB/PB 级、多并发、需要权限治理的企业场景是合适的。但对以下场景它就过度设计了：

• 数据科学家在笔记本上分析一份 20GB 的 Parquet；
• 后端服务需要在请求链路里做一次轻量聚合（比如统计过去 7 天的订单分布）；- 数据管道里的一个「中间转换」步骤，数据量刚过内存但远没到需要集群；
• 边缘设备 / 函数计算（Lambda）里想顺手查一下本地日志。

这些场景的共同特征是：单进程、数据在本地、追求低延迟、零运维。ClickHouse 文章我们之前拆解过，它很强，但它假设你愿意为它配一台服务器。而 DuckDB 的假设是——数据库引擎就跑在你自己的进程里，和你和你的 Python 脚本、你的 Go 二进制共享同一块内存。

1.2 SQLite 的启示与局限

SQLite 证明了「嵌入式关系型数据库」的必要性：它活在应用进程内，零配置，单个文件就是一个库。但 SQLite 是为 OLTP（行存、点查、事务）设计的，它的执行引擎是逐行（row-by-row）解释的。你让它对 1 亿行做 SUM(amount) GROUP BY region，它会慢得让你怀疑人生——因为行存 + 逐行解释完全发挥不出分析负载需要的批量处理能力。

DuckDB 的洞见是：把 SQLite 的「嵌入式」哲学，套在 OLAP 的「列存 + 向量化」引擎上。于是你得到了「分析界的 SQLite」——无需服务、单文件、但跑分析查询飞快。

1.3 2026 年的 DuckDB 坐标

截至 1.5，DuckDB 已经不是玩具：

• 单机 TB 级：官方基准里，单机 DuckDB 在合适的数据布局下能扫描 TB 级 Parquet；
• Lakehouse 接入：原生读写 Parquet、CSV、JSON，支持 Iceberg（含 DML）、Delta 扩展、HTTP(S)/S3 直读；
• 多语言一等公民：Python、R、Node.js、Go、Java、Ruby、C++ 都有官方或准官方绑定；
• 云化：MotherDuck 把 DuckDB 搬上云，提供本地+云端协同；DeepSeek 的 smallpond 也基于 DuckDB 做分布式数据框架；
• LTS 通道：1.4.2 成为长期支持版本，企业可以锁定 LTS 获得稳定 API。

这构成了我们今天拆解的底色：DuckDB 正在把「嵌入式」和「湖仓」这两个看似矛盾的世界缝合起来。

二、核心概念：进程内、列存、向量化到底意味着什么

理解 DuckDB 的性能，必须先理解三个核心概念：进程内（in-process）、列存（columnar）、向量化执行（vectorized execution）。它们不是营销词，而是互相咬合的工程选择。

2.1 进程内：消灭序列化与网络边界

传统数据库的交互模型是这样的：

你的应用 --(SQL over TCP)--> 数据库服务进程 --(读磁盘)--> 结果 --(序列化 TCP)--> 你的应用

每一次查询都有一次网络往返、一次 SQL 解析、一次结果序列化/反序列化。对于大结果集（比如返回 1000 万行），光是「把结果从服务端搬到客户端」这一项的开销就足以杀死交互体验。

DuckDB 的模型是：

你的应用进程
  ├── 你的 Python/Go 代码
  └── DuckDB 引擎（同一地址空间，共享内存）

查询的结果不是「通过网络传回来的一串字节」，而是进程内的一块内存（Arrow 格式的 Data Chunk）。你的 DataFrame 零拷贝地指向它。这意味着：

• 没有网络延迟；
• 没有序列化/反序列化；
• 数据在内存里只存在一份，应用和分析引擎共享。

这就是为什么 DuckDB 能直接 SELECT * FROM 'big.parquet' 然后 .df() 拿到 Pandas DataFrame——它内部就是 Arrow，而 Arrow 和 Pandas 2.0 是零拷贝互通的。

2.2 列存：分析负载的天然拍档

分析查询的经典形态是「宽表、少列、大扫描」：一张 200 列的表，你的查询往往只碰其中 5 列做聚合。行存（SQLite、MySQL）必须把每行 200 列全部读进内存才能取那 5 列，I/O 浪费 97.5%。

列存把同一列的数据连续存放。DuckDB 扫描时只读取查询涉及的列对应的数据块，配合 min/max 统计信息 还能做静态分区裁剪（static pruning）——如果某列是日期且按日期分区，DuckDB 在打开文件前就能跳过明显不匹配的分区。这是一个在 Parquet 上极其显著的速度来源。

2.3 向量化执行：一次处理一批，而不是一行

这是 DuckDB 性能的灵魂。传统解释器（如 SQLite、PostgreSQL 早期执行器）是 Volcano 模型：执行树里每个算子（operator）实现 next()，每次吐出一行，上层算子再处理这一行。问题是：

• 每行一次虚函数调用（virtual dispatch），CPU 分支预测器和流水线被打碎；
• 一次只处理一个标量值，SIMD 指令完全用不上；
• 函数调用开销在亿级数据上会被放大成主要成本。

DuckDB 采用 向量化 / 分批（vectorized / block-oriented）执行：每个算子 next() 一次吐出一个 Data Chunk —— 默认 2048 行的列式批量。算子内部对这 2048 行做**紧凑循环（tight loop）**处理，循环体里是简单的标量运算，现代 CPU 的乱序执行和（如果手写）SIMD 都能充分展开。

// 伪代码：火山模型（逐行）
for each row:
    if (row.filter_cond) output(row)   // 每行一次调用开销

// 伪代码：向量化模型（批量）
chunk = child.next(2048 rows);
mask = evaluate_filter(chunk);          // 一次性对 2048 行求布尔掩码
output(chunk.select(mask));             // 批量投影

这带来的好处是工程上可量化的：

• 函数调用次数降到 1/2048：虚函数开销被摊薄；
• 分支可预测：一个 chunk 内往往同质性高，循环里的分支稳定；
• 缓存友好：列式数据连续存放，预取器（prefetcher）能提前把下一批搬进 L1/L2；
• SIMD 友好：例如对 2048 个 int32 求和，能直接上 AVX2 一次加 8 个。

DuckDB 内部实际上大量使用了推模式（push-based） 与 流水线（pipeline） 的融合：数据从叶子算子（文件扫描）以 chunk 为单位向上流动，流经过滤、投影、聚合，尽量在一个 pipeline 内不落盘。这种「chunk 像水一样流过管道」的意象，正是它快的核心。

三、架构分析：拆开 DuckDB 1.5 的引擎室

3.1 整体架构全景

一个 DuckDB 查询从 con.execute(sql) 到拿到结果，要走过这条流水线：

SQL 文本
  │
  ▼
[1] Parser（词法/语法分析）→ 解析树（Parse Tree）
  │
  ▼
[2] Binder（语义绑定）→ 把表名/列名/类型解析成逻辑计划（Logical Plan）
  │
  ▼
[3] Optimizer（基于规则的优化）→ 谓词下推、列裁剪、公共子表达式消除、连接重排
  │
  ▼
[4] Planner → 物理计划（Physical Plan），决定用 Hash Join 还是 Merge Join
  │
  ▼
[5] Execution Engine（向量化执行）→ 按 pipeline 吐 Data Chunk
  │
  ▼
[6] 存储层（Buffer Manager + 表/索引 + Parquet/CSV/JSON 读取器 + Vortex）
  │
  ▼
结果（Arrow Data Chunk / DataFrame / 流式游标）

我们挑几个和 1.5 强相关的点深入。

3.2 Data Chunk：向量化执行的货币

DataChunk 是 DuckDB 在算子之间传递数据的标准单位，结构大致是：

class DataChunk {
    vector<unique_ptr<Vector>> data;  // 每一列是一个 Vector
    idx_t size;                        // 本 chunk 的行数（≤ STANDARD_VECTOR_SIZE = 2048）
};

class Vector {
    LogicalType type;
    unique_ptr<VectorBuffer> buffer;   // 实际数据（连续内存）
    // 还可能是「字典编码 / 常量 / 序列」等扁平化（flattening）状态
};

关键细节：

• 扁平（Flat）Vector：数据连续存放在一块 int32[2048] 这样的数组里，对 SIMD 最友好；
• 常量（Constant）Vector：整列都是同一个值（比如 WHERE 1=1 的过滤结果），可以直接引用而不复制；
• 字典（Dictionary）Vector：存一个「字典」+「位置索引」，用于去重投影，避免真的复制数据；
• 延迟物化（Late Materialization）：扫描时先只取过滤列建好掩码，最后才去取需要的其它列，减少无效内存访问。

这套 Vector 抽象让 DuckDB 能在「零拷贝、最小物化」的前提下完成复杂查询——这是它内存效率高的根本原因。

3.3 查询优化器：工程师最该懂的 4 件事

DuckDB 的优化器是纯 RBO（基于规则）+ 部分 CBO（基于代价，主要用在连接顺序）。对写查询的人最有用的几条规则：

1. 谓词下推（Predicate Pushdown）：WHERE dt >= '2026-07-01' 会被推到文件扫描算子之前，配合 Parquet 的 min/max 统计直接跳过整批文件/行组（row group）。
2. 列裁剪（Column Elimination）：没在 SELECT/ WHERE/ JOIN 里出现的列，扫描阶段根本不读。
3. 连接顺序重排（Join Reorder）：多表 JOIN 时用动态规划/贪心重排小表驱动的顺序，减少中间物化大小。
4. 公共子表达式消除（CSE）与常量折叠：WHERE amount * 1.08 > 100 里 1.08 被折叠，EXTRACT(year, ts) 在分区已知时被预先计算。

实战建议：在 DuckDB 里，你几乎不需要像在 MySQL 里那样「为了性能手写奇怪的子查询」。把意图写清楚，优化器会下推。你应该把精力放在数据布局（分区、列式文件格式、合理的类型）上，而不是 SQL 技巧上。

3.4 VARIANT 类型：终于能优雅地吃下半结构化数据

这是 1.5 最让我兴奋的特性之一。过去 DuckDB 处理 JSON 有两种别扭方式：

• 用 JSON 类型：存的是「字符串化的 JSON」，访问路径要用 json_extract，类型会退化成 VARCHAR 或 JSON，且每次访问都要重新解析；
• 用 STRUCT：类型必须预先定义，遇到 schema 漂移（同一列里有的行有 score、有的没有）就抓瞎。

VARIANT 是 DuckDB 1.5 引入的一级半结构化类型，它把 JSON 的灵活性 + 列存的性能结合起来：

-- 建表，payload 是一级类型，不要求固定 schema
CREATE TABLE events (
    id   BIGINT,
    ts   TIMESTAMP,
    payload VARIANT
);

INSERT INTO events VALUES
  (1, NOW(), '{"user":"alice","score":95,"tags":["a","b"]}'::JSON),
  (2, NOW(), '{"user":"bob","active":true,"nested":{"x":1}}'::JSON);

-- 直接「点」访问，VARIANT 保留了原始 JSON 的精确类型
-- 注意 score 是 INTEGER、active 是 BOOLEAN、tags 是 LIST，不会全退化成字符串
SELECT
    payload.user,
    payload.score + 5        AS boosted,
    payload.active,
    payload.tags[1]          AS first_tag,
    payload.nested.x
FROM events;

VARIANT 的工程价值：

• 类型保真：score 始终是整数，active 始终是布尔，聚合时不会因类型退化而出错；
• 列式存储半结构化：DuckDB 内部会把 VARIANT 里频繁出现的字段做「展开（flattening）」，让热点字段享受列存扫描速度，冷字段留在变长区；
• schema 漂移友好：不同行结构不同也能共存，非常适合日志、埋点、Webhook 这类天生不规则的数据。

对比一下老写法：

-- 旧：JSON 类型，访问要走函数，结果类型不稳定
SELECT json_extract_string(col, '$.user') FROM t;

-- 新：VARIANT，像访问普通列一样
SELECT col.user FROM t;

3.5 GEOMETRY 内置：空间分析不再需要插件

1.5 把 GEOMETRY 从扩展提升为内置一级类型，配套 ST_* 函数开箱即用：

-- 判断一个点是否落在某个多边形内（配送范围、地理围栏场景）
SELECT ST_Contains(
    ST_GeomFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'),
    ST_Point(5, 5)
) AS inside;   -- true

-- 计算面积
SELECT ST_Area(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))'));  -- 1.0

-- 配合 VARIANT 处理 GeoJSON
SELECT ST_GeomFromGeoJSON(payload.geojson) FROM events;

这对于「带地理信息的事件分析」（比如按配送区域聚合订单）是巨大便利：以前要装 spatial 扩展，现在内核自带。

3.6 Vortex 存储引擎：1.4.2 LTS 的隐藏大招

如果说 1.5 是台前明星，那 Vortex 就是 1.4.2 LTS 埋下的伏笔，也是 DuckDB 向 Lakehouse 演进的关键。

Vortex 是一种新的列式存储布局，目标是：在保持「进程内、文件即数据库」简单模型的同时，获得接近专业湖仓的扫描与压缩效率。它和 DuckDB 一直支持的「直接读 Parquet」互补——Parquet 是交换格式（你用它和别的系统互通），Vortex 是 DuckDB 的原生高效存储（你用它在 DuckDB 内部持久化热数据）。

Vortex 带来的能力（结合 1.4.2 的安全修复与 Iceberg 增强）：

• 更激进的编码/压缩：针对分析负载的列式编码（RLE、字典、位打包），减少 I/O；
• 加密模块加固：1.4.2 修复了加密相关的 4 个严重漏洞（密钥随机数不安全、内存清零被编译器优化掉、GCM→CTR 降级绕过完整性校验），使用 DuckDB 加密功能的用户被强烈建议升级到 1.4.2；
• 与 Iceberg 打通：Iceberg 扩展现在支持完整 DML——INSERT / UPDATE / DELETE，意味着 DuckDB 能作为 Lakehouse 的查询+轻量写入引擎直接操作 Iceberg 表。

-- 1.4.2+：对 Iceberg 表直接做 DML（不再是只读）
ATTACH 's3://my-lake/warehouse' AS lake (TYPE ICEBERG);
UPDATE lake.db.orders SET status = 'shipped' WHERE order_id = 12345;
DELETE FROM lake.db.events WHERE ts < TIMESTAMP '2025-01-01';

这让 DuckDB 的定位从「查 Parquet 的小工具」升级为「能参与湖仓治理的引擎」，和 ClickHouse、PostgreSQL 这类文章里聊的系统形成了互补分工。

3.7 非阻塞检查点（Non-blocking Checkpoint）

DuckDB 的持久化靠 WAL（Write-Ahead Log）+ Checkpoint。旧版本 Checkpoint 是阻塞操作：写入量大时，Checkpoint 会卡住前台写入。1.5 引入非阻塞检查点——Checkpoint 在后台进行，前台写入不再被「冻结」，对「边写边查」的服务型场景（比如一个用 DuckDB 做实时聚合的 API）意义重大。

-- 查看/控制 checkpoint 行为
PRAGMA checkpoint_on_shutdown;          -- 关闭时是否强制 checkpoint
CHECKPOINT;                             -- 手动触发（现在默认尽量不阻塞）

3.8 新排序算法（1.4.0）：3~10 倍提升

排序是数据库最吃性能的操作之一。1.4.0 重写了 sort 算法，核心思想是把 Hash Join / Hash Agg 里验证过的可溢出页面布局（spillable paged layout） 借用到排序上：

• 数据能否溢出到磁盘（超过内存时）；
• 排序过程中是否能持续从磁盘读取（流水化，不全读进来再排）；
• 是否并行（吃满多核）；
• 比较阶段解释开销降到最低（用紧凑的比较器）。

官方基准整体 3 倍以上提升，最快 case 达 10 倍。对你的实际意义：涉及 ORDER BY + LIMIT（排行榜、Top-N）、window 函数的查询会明显变快。

3.9 翻新的 CLI：终端里的分析体验

1.5 重写了命令行客户端，亮点：

• 动态提示：默认显示当前库和 schema，memory D 这类提示让你随时知道身处哪；
• 分页器 + 配色：关键字、字符串、数字各有专属颜色，支持自定义；
• 便捷命令：.highlight_colors、ATTACH 即时切换库等。

$ duckdb
D ATTACH 'analytics.duckdb' AS a;
D USE a;
a D SELECT count(*) FROM events;
┌──────────────┐
│ count_star() │
└──────────────┘
│      1048576 │
└──────────────┘

-- 自定义高亮
a D .highlight_colors column_name darkgreen bold_underline
a D .highlight_colors numeric_value red bold

四、代码实战：今天就把 DuckDB 用起来

下面所有示例均可直接运行（Python 3.10+，DuckDB ≥1.5）。

4.1 零成本查询远程 Parquet

最常见的入门姿势：直接对 S3 / HTTPS 上的 Parquet 跑 SQL，无需下载、无需建表。

import duckdb

con = duckdb.connect()

# 直接 SELECT 一个 Parquet 目录（通配符），DuckDB 会并行扫描 + 谓词下推
sql = """
    SELECT
        airline,
        COUNT(*)                    AS flights,
        AVG(dep_delay)              AS avg_dep_delay,
        quantile_cont(air_time, 0.99) AS p99_air_time
    FROM read_parquet('s3://duckdb-benchmark-data/flights/*.parquet')
    WHERE dep_delay > 0
    GROUP BY airline
    ORDER BY flights DESC
    LIMIT 10
"""
df = con.execute(sql).df()   # 直接拿到 Pandas DataFrame（零拷贝）
print(df)

要点：

• read_parquet('.../*.parquet') 是表函数（table-producing function），把文件当表用；
• S3 读取需要配置凭证：SET s3_region='us-east-1'; SET s3_access_key_id='...'; 或用 httpfs 扩展；
• 结果 .df() 是 Arrow→Pandas 零拷贝，百万行也不卡。

4.2 多源 JOIN：Parquet × CSV × VARIANT

真实 ETL 常要合并多种格式。DuckDB 原生支持，且能顺手用 VARIANT 吃掉不规则的 JSON 列。

con = duckdb.connect('warehouse.duckdb')

con.execute("""
    CREATE OR REPLACE TABLE orders AS
    SELECT * FROM read_csv_auto('orders.csv', header=true);

    -- 把嵌套的扩展字段（不规则 JSON）直接读成 VARIANT
    CREATE OR REPLACE TABLE events AS
    SELECT
        id,
        ts,
        payload::JSON::VARIANT AS payload   -- 文本 JSON → VARIANT
    FROM read_csv_auto('events.csv', header=true);
""")

# 多源 JOIN：订单表 + 事件表（用 VARIANT 里的 user_id 关联）
report = con.execute("""
    SELECT
        o.order_id,
        o.amount,
        e.payload.channel        AS channel,       -- VARIANT 字段直接点出来
        e.payload.score + 10     AS adj_score
    FROM orders o
    JOIN events e
      ON o.user_id = e.payload.user_id::BIGINT
    WHERE o.amount > 100
""").df()

4.3 用 VARIANT 做「无 schema」日志清洗

假设埋点日志是纯文本 JSON，字段随版本漂移：

-- 直接把整列读成 VARIANT，字段不全也不报错
CREATE TABLE logs (raw VARIANT);
INSERT INTO logs SELECT payload::JSON::VARIANT FROM read_json_auto('clickstream.jsonl');

-- 即便某些行没有 `score` 字段，查询也不会崩（返回 NULL）
SELECT
    raw.event       AS event,
    raw.score       AS score,          -- 没有该字段的行得到 NULL
    raw.user.id     AS uid,
    raw.tags[1]     AS first_tag
FROM logs
WHERE raw.event = 'purchase';

对比用 JSON：VARIANT 的访问是类型保真的，.score 是 INTEGER，+ 10 不会因类型退化失败。

4.4 地理围栏分析（GEOMETRY 实战）

-- 每个配送站的覆盖多边形 + 订单坐标，算落在范围内的订单量
CREATE TABLE stations   (id INT, zone GEOMETRY);
CREATE TABLE deliveries (id INT, loc GEOMETRY);

INSERT INTO stations VALUES
  (1, ST_GeomFromText('POLYGON((0 0,0 10,10 10,10 0,0 0))'));
INSERT INTO deliveries VALUES
  (101, ST_Point(5,5)), (102, ST_Point(20,20));

SELECT
    s.id        AS station,
    COUNT(*)    AS in_zone_orders
FROM stations s
JOIN deliveries d
  ON ST_Contains(s.zone, d.loc)
GROUP BY s.id;

4.5 把 DuckDB 嵌进后端服务（Go 示例）

DuckDB 不只是 Python 玩具。Go 服务可以用它做「请求内轻量聚合」：

package main

import (
    "database/sql"
    "fmt"
    _ "github.com/marcboeker/go-duckdb" // DuckDB 的 Go driver（CGO）
)

func main() {
    db, _ := sql.Open("duckdb", "")
    defer db.Close()

    // 直接用内存 DuckDB 分析一批上传的 CSV，无需落库
    rows, _ := db.Query(`
        SELECT region, SUM(amount) AS total
        FROM read_csv_auto('/tmp/upload.csv', header=true)
        WHERE ts >= DATE '2026-07-01'
        GROUP BY region
        ORDER BY total DESC
    `)
    defer rows.Close()
    for rows.Next() {
        var region string
        var total float64
        rows.Scan(&region, &total)
        fmt.Printf("%s: %.2f\n", region, total)
    }
}

适合的场景：管理后台的即席报表、上传文件后的「预览统计」、函数计算里对对象存储文件的临时分析。

4.6 构建本地 ETL 管道

DuckDB 很适合替代一部分 Pandas ETL，尤其数据量超过内存时（DuckDB 能 spill 到磁盘）：

import duckdb

con = duckdb.connect('etl.duckdb')

# 1) 从原始 Parquet 清洗，写入 DuckDB 表（流式，不全载入内存）
con.execute("""
    CREATE TABLE clean AS
    SELECT
        user_id,
        event,
        CAST(ts AS TIMESTAMP) AS ts,
        payload::JSON::VARIANT AS payload
    FROM read_parquet('raw/*.parquet')
    WHERE ts >= TIMESTAMP '2026-07-01'
      AND event IS NOT NULL
""")

# 2) 聚合产出宽表
con.execute("""
    CREATE TABLE daily_kpi AS
    SELECT
        CAST(ts AS DATE) AS day,
        event,
        COUNT(*)                 AS cnt,
        COUNT(DISTINCT user_id) AS uu
    FROM clean
    GROUP BY 1, 2
""")

# 3) 导出为 Parquet 供下游（Spark / 数仓）消费
con.execute("""
    COPY (SELECT * FROM daily_kpi)
    TO 'export/daily_kpi.parquet' (FORMAT PARQUET, PARTITION_BY (day))
""")
print("ETL done, rows:", con.execute("SELECT COUNT(*) FROM clean").fetchone()[0])

4.7 与 Pandas / Polars / Arrow 互操作

import duckdb, pandas as pd

df = pd.DataFrame({"x": range(1_000_000), "y": range(1_000_000)})

# Pandas → DuckDB（relation 接口，惰性，不立即物化）
rel = duckdb.arrow(df)
out = rel.filter("x > 500000").aggregate("SUM(y) AS s").df()
print(out)

# DuckDB → Polars
# import polars as pl
# pl.from_arrow(duckdb.query("SELECT * FROM clean").arrow())

DuckDB 的 Relation API 是惰性的：你链式 .filter().aggregate().join()，它把整条计划攒起来，最后 .df() / .arrow() 时才真正执行——和 Spark DataFrame / Polars LazyFrame 一个思路。

五、性能优化：让 DuckDB 跑满你的机器

DuckDB 开箱已经很快，但以下几条能把它推到极限。

5.1 数据布局优于 SQL 技巧

DuckDB 优化器已经很强，你最大的杠杆是数据怎么存：

• 用 Parquet 而不是 CSV：Parquet 列存 + 内嵌统计信息，让谓词下推和列裁剪生效；CSV 每次都要解析文本。
• 按常用过滤列分区：PARTITION_BY (day, region) 让 DuckDB 跳过无关分区。
• 合理设置行组大小：Parquet row group 太大或太小都影响裁剪粒度，默认通常够用。

-- 导出时分区，查询时自动裁剪
COPY (SELECT * FROM events)
TO 'events/' (FORMAT PARQUET, PARTITION_BY (day));

-- 查询只会打开 day='2026-07-18' 的分区
SELECT COUNT(*) FROM 'events/day=2026-07-18/*.parquet';

5.2 用 EXPLAIN ANALYZE 看真实瓶颈

不要猜性能，要看计划：

-- 看逻辑/物理计划
EXPLAIN SELECT ...;

-- 看实际运行耗时（含每个算子的真实行数与时间）
PRAGMA enable_profiling = 'query_tree';
EXPLAIN ANALYZE SELECT region, SUM(amount)
               FROM read_parquet('raw/*.parquet')
               GROUP BY region;

输出会告诉你：是「SCAN」慢（I/O、没下推）、「HASH_GROUPBY」慢（内存/聚合），还是「PROJECTION」慢（表达式复杂）。针对性优化。

5.3 内存与溢出（Spill）

超出内存时，DuckDB 默认把中间结果 spill 到磁盘（/tmp 或 temp_directory）：

-- 限制内存上限（避免吃光机器）
SET memory_limit = '4GB';
-- 设置溢出目录（用高速盘）
SET temp_directory = '/mnt/nvme/duckdb_tmp';

经验：给 DuckDB 的 memory_limit 设为物理内存的 60~80%，留点给 OS 和文件系统缓存，整体吞吐反而更高（避免 OS 开始疯狂 swap）。

5.4 善用并行

DuckDB 自动并行扫描和算子。可通过线程数控制：

SET threads = 8;   -- 默认是 CPU 核数

注意：并行对扫描大文件/多文件收益最大；对小数据（几千行）反而因线程调度开销变慢。小查询别强行多线程。

5.5 VARIANT 不是银弹

VARIANT 很香，但「全塞 VARIANT」会牺牲列存优势——热点字段不会被展开优化。经验法则：

• 字段稳定且频繁过滤/聚合 → 用显式列（INT/VARCHAR/TIMESTAMP）；
• 字段稀疏、不规则、偶尔访问 → 用 VARIANT。

5.6 与 Pandas / Spark 的选型边界

一句话：DuckDB 接管「单机、本地、湖仓读写、嵌入应用」的 80% 分析需求；需要分布式或强服务端治理时才上 ClickHouse / Spark。

5.7 一个真实基准观感

社区常见的对比（同一台 8 核笔记本，10GB Parquet，GROUP BY 多列聚合）：

• Pandas：内存峰值高，常因 groupby 物化崩；
• DuckDB：内存平稳（可 spill），耗时约为 Pandas 的 1/5 ~ 1/10；
• Spark 单机：启动开销大、配置繁琐，单核效率不如 DuckDB，仅在数据远超内存且要复杂 shuffle 时胜出。

数字会因数据和机器而异，但方向稳定：单机分析，DuckDB 是性价比之王。

六、总结与展望：嵌入式湖仓的时代来了

回头看 DuckDB 的演进轨迹，你会发现一条清晰的主线：

1. 1.0~1.3：证明「进程内向量化 OLAP」可行，吃掉 SQLite 做不好的分析场景；
2. 1.4.x（LTS）：引入 Vortex 存储引擎、加固加密、补全 Iceberg DML，向 Lakehouse 伸出手；
3. 1.5（Variegata）：VARIANT 让半结构化数据变得优雅，GEOMETRY 内置让空间分析零成本，非阻塞 Checkpoint 让它能在服务型场景里「边写边查」。

它正在做的，是把过去被「客户端-服务器数据库」垄断的能力，重新塞回单个进程、单个文件、零配置的形态里——就像 SQLite 当年对 OLTP 做的那样，只是这次是给分析负载。

什么情况下我推荐你上 DuckDB

• 你受够了为一条 GROUP BY 拉集群；
• 你的数据在对象存储（S3）的 Parquet 里，只想即席查一下；
• 你要在后端服务里嵌一个「轻量分析」能力，又不想养一个数据库服务；
• 你在做数据管道，需要比 Pandas 稳、比 Spark 轻的 ETL 步骤；
• 你有大量不规则 JSON 日志，VARIANT 正合适。

它的边界要诚实承认

DuckDB 不是分布式数据库，不解决多节点一致性与水平扩展；它的并发写能力（多_writer）也有限，本质上是「单写多读 / 分析优先」。需要这些，请回到 ClickHouse、PostgreSQL 或专业数仓——这些我们都有专门的深度拆解。

2026 年之后的想象空间

• MotherDuck + 本地协同：本地 DuckDB 处理热数据，云端做全局聚合，无缝衔接；
• smallpond 式分布式框架：在 DuckDB 之上做「薄分布式」，让单机引擎吃到多机；
• Vortex 成熟：原生存储追上专业列存格式，DuckDB 文件本身成为高效交换介质；
• 与 AI 检索结合：DuckDB 做结构化过滤，向量库（如我们拆解过的 Qdrant）做语义检索，混合查询成为 RAG 的标配。

对工程师来说，DuckDB 1.5 最大的礼物不是某个单一特性，而是一种心态解放：下次再遇到「我就想查一下这批数据」，你不必再犹豫「要不要起服务」。装上它，写一行 SQL，答案就来了。这种「分析的自由感」，正是嵌入式数据库最迷人的地方。

附：快速上手清单

# 安装
pip install duckdb>=1.5        # Python
brew install duckdb            # macOS CLI

# 最小可用
python -c "import duckdb; print(duckdb.query('SELECT 42 AS answer').df())"

# 直查 Parquet
duckdb -c "SELECT region, SUM(amount) FROM 'data/*.parquet' GROUP BY region"

选型来源关键词：「数据库技术 / DuckDB 1.5 新特性 / 嵌入式 OLAP / Vortex 引擎 / VARIANT 类型」。本文所有代码示例均基于 DuckDB 1.5 语法，已尽量标注版本依赖。