在数据分析场景中，DuckDB 作为一款 “嵌入式 OLAP 数据库”，以其无需部署、SQL 兼容、性能优异的特点，成为 Python 数据分析的轻量优选。它支持直接查询 CSV/Parquet 等文件，无缝衔接 pandas/matplotlib，无需复杂配置即可快速落地数据分析需求。本文详解 Python 集成 DuckDB 的完整流程，包含数据读取、SQL 分析、结果可视化等核心场景，代码精简无冗余，帮助开发者快速上手。

一、核心原理与环境准备

1. 核心逻辑

DuckDB 的核心优势是 “嵌入式 + OLAP 优化”，Python 中使用的核心流程：

关键工具协同：

• DuckDB：负责 SQL 解析、数据查询（支持批量 / 增量查询，性能优于传统 Python 数据框架）；

• pandas：接收 DuckDB 查询结果，进行数据预处理；

• matplotlib/seaborn：结果可视化，直观呈现分析结论。

2. 环境准备

工具 / 依赖	版本要求	作用描述
Python	3.7+	核心运行环境
DuckDB	0.8+	嵌入式 OLAP 数据库核心依赖
pandas	1.0+	数据格式转换与预处理
matplotlib/seaborn	3.0+/0.10+	数据可视化
pip	20.0+	Python 包管理工具

3. 依赖安装命令

通过 pip 快速安装所需依赖（仅需 3 行命令）：

pip install duckdb==0.9.2

pip install pandas matplotlib seaborn

二、数据源准备（示例文件）

使用与前文一致的data.csv文件（确保数据连贯性，便于对比分析），包含 “日期、销量、销售额、地区、客户类型” 字段：

日期,销量,销售额,地区,客户类型

2024-01-01,120,12000,华东,个人

2024-01-02,150,15600,华北,企业

2024-01-03,130,13200,华南,个人

2024-01-04,180,19800,华东,企业

2024-01-05,200,22000,华北,个人

2024-01-06,170,18700,华南,企业

2024-01-07,160,17600,华东,个人

2024-01-08,190,20900,华北,企业

2024-01-09,140,15400,华南,个人

2024-01-10,210,23100,华东,企业

将文件保存至 Python 项目根目录，便于 DuckDB 直接读取。

三、核心代码实现（DuckDB 数据分析全流程）

1. 基础配置：连接 DuckDB + 读取数据

DuckDB 支持两种读取方式：直接查询 CSV 文件（无需加载全量数据）、导入为 DuckDB 表（适合多轮查询），代码如下：

import duckdb

import pandas as pd

import matplotlib.pyplot as plt

import seaborn as sns

# 设置中文字体（避免中文乱码）

plt.rcParams['font.sans-serif'] = ['SimHei'] # Windows系统

# plt.rcParams['font.sans-serif'] = ['Arial Unicode MS'] # Mac系统

plt.rcParams['axes.unicode_minus'] = False

# 1. 连接DuckDB（嵌入式数据库，无需服务，自动创建内存数据库）

con = duckdb.connect(database=':memory:') # database参数指定内存模式，也可指定本地文件（如'data.duckdb'）

# 2. 方式1：直接查询CSV文件（无需加载全量数据，适合一次性查询）

print("=== 直接查询CSV文件 ===")

query1 = """

SELECT 地区, SUM(销量) AS 总销量, AVG(销售额) AS 平均销售额

FROM 'data.csv' -- 直接指定CSV文件路径

GROUP BY 地区

ORDER BY 总销量 DESC

"""

result1 = con.execute(query1).fetchdf() # 结果直接转为DataFrame

print(result1)

# 3. 方式2：导入CSV为DuckDB表（适合多轮查询，提升性能）

con.execute("CREATE TABLE IF NOT EXISTS sales_data AS SELECT * FROM 'data.csv'")

print("\n=== 查看DuckDB表结构 ===")

con.execute("DESCRIBE sales_data").fetchdf() # 查看表结构

# 验证表数据

print("\n=== 查看表前5行 ===")

result2 = con.execute("SELECT * FROM sales_data LIMIT 5").fetchdf()

print(result2)

2. 核心 SQL 分析（多场景查询示例）

基于 DuckDB 表执行复杂 SQL 查询，覆盖分组统计、过滤、排序等常见分析场景：

# 1. 按客户类型+地区分组，统计销量和销售额

print("=== 客户类型+地区销量统计 ===")

query3 = """

SELECT

客户类型,

地区,

SUM(销量) AS 总销量,

SUM(销售额) AS 总销售额,

MAX(销售额) AS 最高单笔销售额

FROM sales_data

GROUP BY 客户类型, 地区

HAVING SUM(销量) > 100 -- 过滤总销量>100的分组

ORDER BY 总销售额 DESC

"""

result3 = con.execute(query3).fetchdf()

print(result3)

# 2. 时间维度分析（转换日期格式，按日期统计）

print("\n=== 每日销量趋势 ===")

query4 = """

SELECT

日期,

SUM(销量) AS 当日销量,

SUM(销售额) AS 当日销售额

FROM sales_data

WHERE 日期 BETWEEN '2024-01-01' AND '2024-01-10'

GROUP BY 日期

ORDER BY 日期

"""

result4 = con.execute(query4).fetchdf()

# 转换日期格式（便于后续可视化）

result4['日期'] = pd.to_datetime(result4['日期'])

print(result4)

# 3. 计算各地区销售额占比

print("\n=== 各地区销售额占比 ===")

query5 = """

WITH total_sales AS (

SELECT SUM(销售额) AS 总销售额 FROM sales_data

)

SELECT

地区,

SUM(销售额) AS 地区销售额,

(SUM(销售额) / (SELECT 总销售额 FROM total_sales)) * 100 AS 占比(%)

FROM sales_data

GROUP BY 地区

ORDER BY 地区销售额 DESC

"""

result5 = con.execute(query5).fetchdf()

print(result5)

3. 结果可视化（衔接 matplotlib）

将 DuckDB 查询结果（DataFrame）通过可视化呈现，直观展示分析结论：

# 1. 柱状图：各地区总销量对比（基于result1）

plt.figure(figsize=(8, 5))

sns.barplot(x='地区', y='总销量', data=result1, palette='Set2')

plt.title('各地区总销量对比', fontsize=14, fontweight='bold')

plt.xlabel('地区', fontsize=12)

plt.ylabel('总销量（件）', fontsize=12)

# 添加数值标签

for i, v in enumerate(result1['总销量']):

plt.text(i, v + 20, str(v), ha='center', fontsize=11)

plt.tight_layout()

plt.savefig('duckdb_地区销量柱状图.png', dpi=300)

plt.show()

# 2. 折线图：每日销量趋势（基于result4）

plt.figure(figsize=(10, 6))

plt.plot(result4['日期'], result4['当日销量'], marker='o', color='#2E86AB', linewidth=2)

plt.title('2024年1月每日销量趋势', fontsize=14, fontweight='bold')

plt.xlabel('日期', fontsize=12)

plt.ylabel('当日销量（件）', fontsize=12)

plt.grid(True, alpha=0.3)

plt.xticks(rotation=45)

plt.tight_layout()

plt.savefig('duckdb_每日销量折线图.png', dpi=300)

plt.show()

# 3. 饼图：各地区销售额占比（基于result5）

plt.figure(figsize=(8, 8))

plt.pie(

result5['地区销售额'],

labels=result5['地区'],

autopct='%1.1f%%', # 显示百分比（保留1位小数）

startangle=90,

colors=['#FF6B6B', '#4ECDC4', '#45B7D1'],

explode=(0.05, 0, 0) # 突出显示第一块

)

plt.title('各地区销售额占比', fontsize=14, fontweight='bold')

plt.axis('equal') # 保证饼图为正圆形

plt.tight_layout()

plt.savefig('duckdb_地区销售额占比饼图.png', dpi=300)

plt.show()

# 关闭DuckDB连接

con.close()

四、运行与测试步骤

1. 准备data.csv文件，放在 Python 项目根目录；

1. 复制上述代码，按顺序执行（支持 PyCharm、Jupyter Notebook 等环境）；

1. 观察控制台输出：查看各 SQL 查询的 DataFrame 结果；

1. 验证可视化图表：项目目录下生成 3 张 PNG 图表，分别对应地区销量、每日趋势、销售额占比。

五、避坑指南与常见问题解决

1. CSV 文件读取失败（FileNotFoundError）

• 原因：文件路径错误，或文件名拼写错误；

• 解决：

1. 1. 确保 CSV 文件与 Python 脚本在同一目录；

1. 1. 若不在同一目录，使用绝对路径（如'C:/data/data.csv'或'/Users/xxx/data.csv'）；

1. 1. 路径中避免中文和空格（或用引号包裹路径）。

2. 日期格式解析错误

• 原因：CSV 中日期格式与 DuckDB 默认解析格式不匹配；

• 解决：查询时显式转换日期格式：

SELECT STRPTIME(日期, '%Y-%m-%d') AS 标准日期 FROM sales_data

其中%Y-%m-%d为 CSV 中的日期格式（根据实际调整，如%m/%d/%Y）。

3. 内存占用过高（处理大文件时）

• 原因：直接导入大文件为 DuckDB 表时，全量加载占用内存；

• 解决：

1. 1. 使用 DuckDB 的分区查询功能：SELECT * FROM 'data.csv' WHERE 地区='华东'（仅加载符合条件的数据）；

1. 1. 将数据库保存为本地文件（duckdb.connect(database='sales.duckdb')），而非内存模式；

1. 1. 对于超大数据（GB 级），结合chunksize分批读取：

con.execute("CREATE TABLE sales_data AS SELECT * FROM read_csv_auto('data.csv', chunksize=10000)")

4. 中文乱码（查询结果中中文显示异常）

• 原因：CSV 文件编码与 DuckDB 读取编码不一致（默认 UTF-8）；

• 解决：读取时指定编码格式：

con.execute("CREATE TABLE sales_data AS SELECT * FROM read_csv('data.csv', encoding='GBK')")

（根据 CSV 实际编码调整，如GB2312、UTF-8）。

六、进阶优化与扩展场景

1. 核心优化点

• 性能优化：

1. 1. 对于多轮查询，优先导入为 DuckDB 表（比重复读取 CSV 快 10 倍以上）；

1. 1. 为频繁查询的字段创建索引：con.execute("CREATE INDEX idx_region ON sales_data(地区)")；

1. 1. 批量插入数据：con.execute("INSERT INTO sales_data SELECT * FROM 'data2.csv'")。

• 数据格式支持：DuckDB 不仅支持 CSV，还支持 Parquet、JSON 等格式，读取方式类似：

SELECT * FROM 'data.parquet' -- 读取Parquet文件

SELECT * FROM 'data.json' -- 读取JSON文件

• 环境隔离：将 DuckDB 数据库保存为本地文件（如sales.duckdb），支持跨会话复用数据：

con = duckdb.connect(database='sales.duckdb', read_only=False) # 读写模式

2. 扩展场景

• 联合查询多文件：同时查询多个 CSV/Parquet 文件，合并分析：

SELECT 地区, SUM(销量) FROM (

SELECT * FROM 'data1.csv'

UNION ALL

SELECT * FROM 'data2.csv'

) GROUP BY 地区

• 与 pandas 深度协同：DuckDB 可直接查询 pandas DataFrame，无需导入表：

df = pd.read_csv('data.csv')

result = con.execute("SELECT 地区, SUM(销量) FROM df GROUP BY 地区").fetchdf()

• 复杂统计分析：使用 DuckDB 内置函数进行统计计算（如方差、分位数）：

SELECT

地区,

STDDEV(销量) AS 销量标准差,

PERCENTILE_CONT(销量, 0.5) AS 销量中位数

FROM sales_data

GROUP BY 地区

总结

Python+DuckDB 的数据分析方案，核心优势是 “轻量高效、门槛低、性能强”：

1. 无需部署数据库服务，嵌入式运行，1 行代码即可连接；

1. 支持 SQL 直接查询文件，无需全量加载，处理大文件更高效；

1. 无缝衔接 pandas、matplotlib，现有数据分析流程无需大幅修改；

1. 核心代码仅 100 余行，覆盖数据读取、SQL 分析、可视化全流程，适合新手快速上手。

该方案适用于日常数据分析、报告制作、小中型数据集（GB 级以内）分析等场景，尤其适合需要频繁使用 SQL 但不想部署复杂数据库的开发者。相比传统 “pandas+SQLAlchemy” 方案，DuckDB 的查询速度提升 3-10 倍，且无需关注数据库配置，真正实现 “开箱即用” 的轻量数据分析。