【最全详解】DuckDB Python 全套 API 语法、参数与实战用法（零基础全覆盖）

文章目录

• • 一、前言
  • • 适用人群
    • 学习收获
  • 二、环境准备与安装
  • • [2\.1 安装依赖](#2.1 安装依赖)
    • [2\.2 基础入门概念](#2.2 基础入门概念)
  • [三、DuckDB Python 基础核心 API（连接类）](#三、DuckDB Python 基础核心 API（连接类）)
  • • [3\.1 duckdb\.connect\(\) 数据库连接 API](#3.1 duckdb.connect\(\) 数据库连接 API)
    • [3\.2 连接关闭 API：close\(\)](#3.2 连接关闭 API：close\(\))
  • [四、核心查询执行 API（最常用）](#四、核心查询执行 API（最常用）)
  • • [4\.1 conn\.sql\(\) 执行 SQL 语句 API](#4.1 conn.sql\(\) 执行 SQL 语句 API)
    • [4\.2 conn\.execute\(\) 底层执行 API](#4.2 conn.execute\(\) 底层执行 API)
    • [4\.3 查询结果解析 API（fetch 系列）](#4.3 查询结果解析 API（fetch 系列）)
  • [五、结果集转换 API（Pandas/NumPy/List）](#五、结果集转换 API（Pandas/NumPy/List）)
  • • [5\.1 df\(\) 转为 Pandas DataFrame](#5.1 df\(\) 转为 Pandas DataFrame)
    • [5\.2 arrow\(\) 转为 Arrow Table（高性能）](#5.2 arrow\(\) 转为 Arrow Table（高性能）)
    • [5\.3 numpy\(\) 转为 NumPy 数组](#5.3 numpy\(\) 转为 NumPy 数组)
    • [5\.4 fetch\_df\(\) 直接查询返回 DataFrame](#5.4 fetch_df\(\) 直接查询返回 DataFrame)
  • [六、事务管理 API（生产必备）](#六、事务管理 API（生产必备）)
  • • [6\.1 事务三大核心 API](#6.1 事务三大核心 API)
  • [七、文件读写 API（CSV/Parquet/JSON 神器）](#七、文件读写 API（CSV/Parquet/JSON 神器）)
  • • [7\.1 读取文件 API（原生 SQL 函数 \+ Python 适配）](#7.1 读取文件 API（原生 SQL 函数 + Python 适配）)
    • [7\.2 导出文件 API](#7.2 导出文件 API)
  • [八、Pandas 交互全量 API](#八、Pandas 交互全量 API)
  • • [8\.1 直接查询 Pandas DataFrame](#8.1 直接查询 Pandas DataFrame)
    • [8\.2 register\(\) 注册自定义表 API](#8.2 register\(\) 注册自定义表 API)
    • [8\.3 unregister\(\) 注销表](#8.3 unregister\(\) 注销表)
  • [九、数据库配置 API（性能优化核心）](#九、数据库配置 API（性能优化核心）)
  • • [9\.1 全局配置参数 set\(\)](#9.1 全局配置参数 set\(\))
    • [9\.2 获取当前配置 show\(\)](#9.2 获取当前配置 show\(\))
  • [十、元数据查询 API（表结构/字段/数据库信息）](#十、元数据查询 API（表结构/字段/数据库信息）)
  • [十一、自定义函数 API（UDF 高阶）](#十一、自定义函数 API（UDF 高阶）)
  • • [11\.1 create\_function 注册 Python 自定义函数](#11.1 create_function 注册 Python 自定义函数)
  • [十二、内存与资源管理 API](#十二、内存与资源管理 API)
  • • [12\.1 检查内存占用](#12.1 检查内存占用)
    • [12\.2 手动释放内存](#12.2 手动释放内存)
  • [十三、常用 API 速查清单（极简汇总）](#十三、常用 API 速查清单（极简汇总）)
  • 十四、开发最佳实践与避坑总结
  • • [14\.1 最佳实践](#14.1 最佳实践)
    • [14\.2 常见坑点](#14.2 常见坑点)
  • 十五、全文总结

一、前言

DuckDB 是一款嵌入式、轻量级、超快的分析型数据库，被称为"数据分析界的 SQLite"。无需独立服务、无需部署、零配置，完美适配 Python 数据分析、离线数仓、ETL 清洗、大数据交互式查询场景。

相比于 Pandas，DuckDB 支持标准 SQL、超大文件流式查询、复杂聚合、窗口函数、JOIN 优化；相比于 Spark/ClickHouse，DuckDB 开箱即用、无集群成本、本地极速运行。

本文系统性全覆盖 Python DuckDB 官方所有核心 API，统一讲解：语法原型、参数详解、返回值、可运行实战代码、适用场景、避坑要点，一文搞定 DuckDB Python 所有开发用法，无需翻阅官方文档。

适用人群

• Python 数据分析、ETL 开发工程师

• 想要用 SQL 替代 Pandas 复杂数据处理的开发者

• 需要本地极速分析超大 CSV/Parquet 文件的学习者

• 想要全面掌握 DuckDB Python API 的技术从业者

学习收获

• 掌握 DuckDB 连接、查询、事务、读写文件、Pandas 交互全套 API

• 熟练掌握配置优化、自定义函数、元数据查询、内存管理高阶用法

• 规避日常开发 90% 的 DuckDB 报错与坑点

• 拥有可直接复用的 DuckDB 生产级代码模板

二、环境准备与安装

2.1 安装依赖

支持 Python3.7+，一键安装：

pip install duckdb -U

2.2 基础入门概念

• 内存数据库：默认模式，程序关闭数据丢失，速度最快，适合临时分析

• 持久化数据库：绑定本地 .db 文件，数据落地磁盘，可重复使用

• 核心优势：原生支持 Pandas/NumPy/CSV/Parquet/JSON 直接查询，无需导入内存

---

三、DuckDB Python 基础核心 API（连接类）

3.1 duckdb.connect() 数据库连接 API

作用：创建 DuckDB 数据库连接，支持内存库/持久化文件库

语法原型

duckdb.connect(database: str = ":memory:", read_only: bool = False, config: dict = None)

参数详解

• database ：数据库路径，默认 :memory: 内存数据库；传入 xxx.db 即为磁盘持久化数据库

• read_only：是否只读模式，默认 False；开启后禁止建表、插入、修改数据

• config：全局配置字典，用于设置内存、线程、超时、压缩等参数

返回值：DuckDB 连接对象 (DuckDBPyConnection)

实战代码

import duckdb

# 1. 内存数据库（临时，程序结束丢失）
conn_mem = duckdb.connect()

# 2. 持久化数据库（落地磁盘，可重复打开）
conn_disk = duckdb.connect("test_duckdb.db")

# 3. 只读模式打开已有数据库
conn_read = duckdb.connect("test_duckdb.db", read_only=True)

# 4. 带配置项初始化连接
conn_config = duckdb.connect(
    "test_config.db",
    config={
        "memory_limit": "2GB",
        "threads": 4
    }
)

适用场景

• 临时数据分析、脚本运行使用内存库

• 长期存储、迭代计算、离线数仓使用持久化 db 文件

避坑提示

• 多次 connect 同一个 db 文件不会报错，但建议单进程单连接

• 只读模式下执行 DDL/DML 语句会直接报错

3.2 连接关闭 API：close()

作用：关闭数据库连接，释放文件句柄与内存资源

语法原型

conn.close()

实战用法

conn = duckdb.connect("test.db")
# 执行SQL操作...
conn.close()

最佳实践：推荐使用 with 上下文自动关闭连接

with duckdb.connect("test.db") as conn:
    res = conn.sql("SELECT 1")
    print(res)

---

四、核心查询执行 API（最常用）

4.1 conn.sql() 执行 SQL 语句 API

作用：执行任意 DDL/DML/DQL SQL 语句，支持查询、建表、插入、修改、删除

语法原型

conn.sql(query: str)

参数：query 为标准 DuckDB SQL 字符串

返回值：DuckDBPyRelation 结果集对象，支持转 Pandas、List、Dict

完整实战

import duckdb

conn = duckdb.connect()

# 简单查询
res = conn.sql("SELECT 1 AS id, 'duckdb' AS name")
print(res)

# 建表
conn.sql("CREATE TABLE user(id INT, name VARCHAR, age INT)")

# 插入数据
conn.sql("INSERT INTO user VALUES (1, '张三', 20), (2, '李四', 25)")

# 查询表数据
res = conn.sql("SELECT * FROM user")
print(res)

4.2 conn.execute() 底层执行 API

作用：底层 SQL 执行接口，支持参数化查询，防止 SQL 注入

语法原型

conn.execute(query: str, parameters: tuple = ())

实战参数化查询（推荐生产使用）

conn = duckdb.connect()
conn.sql("CREATE TABLE score(name VARCHAR, score INT)")

# 参数化插入，避免注入
conn.execute("INSERT INTO score VALUES (?, ?)", ("小明", 98))

res = conn.execute("SELECT * FROM score").fetchall()
print(res)

4.3 查询结果解析 API（fetch 系列）

用于解析 execute 执行后的结果集，是高频工具 API

语法与用法

conn = duckdb.connect()
conn.sql("CREATE TABLE t(id INT); INSERT INTO t VALUES (1),(2),(3)")

cur = conn.execute("SELECT * FROM t")

# 获取所有结果 list[tuple]
print(cur.fetchall())

# 获取第一条结果
print(cur.fetchone())

# 获取指定条数
print(cur.fetchmany(2))

---

五、结果集转换 API（Pandas/NumPy/List）

DuckDB 最大优势：查询结果一键转为各类数据结构

5.1 df() 转为 Pandas DataFrame

res_df = conn.sql("SELECT * FROM user").df()
print(res_df)

5.2 arrow() 转为 Arrow Table（高性能）

res_arrow = conn.sql("SELECT * FROM user").arrow()

5.3 numpy() 转为 NumPy 数组

res_np = conn.sql("SELECT age FROM user").numpy()

5.4 fetch_df() 直接查询返回 DataFrame

df = conn.execute("SELECT * FROM user").fetch_df()

---

六、事务管理 API（生产必备）

DuckDB 完整支持 ACID 事务，默认自动提交

6.1 事务三大核心 API

• conn.begin()：开启事务

• conn.commit()：提交事务

• conn.rollback()：回滚事务

事务实战模板

conn = duckdb.connect("transaction.db")

try:
    conn.begin()
    conn.sql("INSERT INTO user VALUES (3, '王五', 30)")
    conn.sql("INSERT INTO score VALUES ('王五', 88)")
    # 无异常则提交
    conn.commit()
    print("事务提交成功")
except Exception as e:
    conn.rollback()
    print("事务回滚：", e)

---

七、文件读写 API（CSV/Parquet/JSON 神器）

DuckDB 最核心特色：直接查询本地文件，无需载入内存

7.1 读取文件 API（原生 SQL 函数 + Python 适配）

conn = duckdb.connect()

# 1. 查询CSV文件
df_csv = conn.sql("SELECT * FROM 'test.csv' LIMIT 10").df()

# 2. 查询Parquet文件（大数据首选）
df_pq = conn.sql("SELECT * FROM 'data.parquet'").df()

# 3. 查询JSON文件
df_json = conn.sql("SELECT * FROM 'data.json'").df()

7.2 导出文件 API

# 导出CSV
conn.sql("COPY (SELECT * FROM user) TO 'user.csv' (HEADER, DELIMITER ',')")

# 导出Parquet
conn.sql("COPY (SELECT * FROM user) TO 'user.parquet'")

---

八、Pandas 交互全量 API

8.1 直接查询 Pandas DataFrame

DuckDB 可以直接把 DataFrame 当做数据表查询，无需入库

import pandas as pd

df = pd.DataFrame({
    "id": [1,2,3],
    "name": ["A","B","C"],
    "val": [10,20,30]
})

# 直接SQL查询DataFrame
res = duckdb.sql("SELECT * FROM df WHERE val > 15").df()
print(res)

8.2 register() 注册自定义表 API

作用：将变量、DataFrame、数组注册为数据库表，全局可查询

conn = duckdb.connect()
df_test = pd.DataFrame({"x":[1,2,3]})

# 注册为数据表
conn.register("temp_table", df_test)
res = conn.sql("SELECT * FROM temp_table")
print(res)

8.3 unregister() 注销表

conn.unregister("temp_table")

---

九、数据库配置 API（性能优化核心）

9.1 全局配置参数 set()

语法

conn.execute("SET 参数名 = 值")

常用生产配置

conn = duckdb.connect()
# 最大内存
conn.execute("SET memory_limit = '4GB'")
# 最大线程数
conn.execute("SET threads = 8")
# 查询超时时间
conn.execute("SET query_timeout = 300")
# 开启持久化WAL日志
conn.execute("SET enable_wal = true")

9.2 获取当前配置 show()

print(conn.sql("SHOW ALL SETTINGS").df())

---

十、元数据查询 API（表结构/字段/数据库信息）

conn = duckdb.connect()
conn.sql("CREATE TABLE student(id INT, name VARCHAR, score FLOAT)")

# 查询所有表
print(conn.sql("SHOW TABLES").df())

# 查询表结构
print(conn.sql("DESCRIBE student").df())

# 查询数据库版本
print(conn.sql("SELECT version()").fetchone())

---

十一、自定义函数 API（UDF 高阶）

11.1 create_function 注册 Python 自定义函数

作用：将 Python 函数注册为 SQL 函数，在 SQL 中直接调用

import duckdb

conn = duckdb.connect()

# 定义Python函数
def add_two(x: int) -> int:
    return x + 2

# 注册为SQL UDF
conn.create_function("sql_add_two", add_two)

# SQL中调用
res = conn.sql("SELECT sql_add_two(10) AS res")
print(res)

---

十二、内存与资源管理 API

12.1 检查内存占用

print(conn.sql("PRAGMA memory_stats").df())

12.2 手动释放内存

conn.execute("VACUUM")
conn.execute("CHECKPOINT")

• VACUUM：整理碎片、回收空闲空间

• CHECKPOINT：落地WAL日志，固化数据

---

十三、常用 API 速查清单（极简汇总）

API 功能	核心语法
创建连接	duckdb.connect(path, config)
执行SQL	conn.sql() / conn.execute()
结果转DataFrame	res.df() / fetch_df()
注册变量为表	conn.register()
事务控制	begin() / commit() / rollback()
自定义UDF	conn.create_function()
资源回收	VACUUM / CHECKPOINT

---

十四、开发最佳实践与避坑总结

14.1 最佳实践

• 临时分析用内存库，长期任务用 .db 持久化库

• 批量操作优先使用参数化 execute，防 SQL 注入

• 超大文件优先直接查询 Parquet，不读取到 Pandas

• 生产环境务必配置 memory_limit、threads 防止内存溢出

• 数据更新场景必须加事务，保证数据一致性

14.2 常见坑点

• 内存库数据仅当前连接有效，关闭连接数据清空

• 只读模式无法执行 DDL/DML

• 大查询不限制内存会导致 OOM 崩溃

• 注册的临时表仅当前连接有效

十五、全文总结

本文完整覆盖了 DuckDB Python 全部官方核心 API，包含连接管理、SQL 执行、结果解析、Pandas 交互、文件读写、事务、配置优化、自定义函数、内存管理、元数据查询所有能力。

DuckDB 凭借零部署、极速分析、无缝对接 Python 生态的能力，已经成为替代传统 Pandas 复杂分析、轻量化离线数仓的最优方案之一。掌握全套 API 可以极大提升数据分析、ETL、数据清洗的开发效率。