5.1 编程接口：Python与CLI

5.1 编程接口：Python与CLI

本节摘要：命令行客户端与 Python 接口共享同一个引擎，差别在工作形态：前者是"即席验算与管道处理"的快刀，后者是"应用集成与自动化"的正式通道。本节把两个接口的核心用法过一遍，并给出分工心法。

先说命令行：一把快刀

命令行客户端是验证想法最快的地方——打开即查，不写一行宿主代码。前面章节的示例都假定在命令行里执行，这里补齐它作为日常工具的完整面貌：

-- 启动即用的会话：内存库 or 指定文件库
-- 命令行: duckdb                      （纯内存库，退出即消散）
-- 命令行: duckdb analytics.duckdb     （打开或创建文件库）

-- 会话内直接查文件，不落任何库
SELECT status, count(*) FROM read_csv_auto('trades.csv') GROUP BY status;

-- 结果直接落成压缩的列式文件，一条 SQL 完成格式转换
COPY (SELECT * FROM read_csv_auto('trades.csv'))
TO 'trades.parquet' (FORMAT parquet, COMPRESSION zstd);
​

命令行的杀手锏是管道组合：配合操作系统的管道与重定向，它能嵌进任何脚本环境——下载器吐出的文件直接喂给查询，查询结果导成 Parquet 交给下游。数据工程的很多胶水环节，用命令行比写正式脚本更轻。把 CSV 转 Parquet 那条 SQL 值得背下来：格式转换是它最高频的用武之地之一。

再说 Python：正式通道

Python 接口是使用最广的入口。安装一个包即得完整引擎，连接、查询、取结果三步走：

import duckdb

# 打开文件库（不传路径则是内存库）
con = duckdb.connect("analytics.duckdb")

# 查询返回结果关系对象，可继续链式操作
rel = con.sql("""
    SELECT hour(trade_time) AS 小时, count(*) AS 退款笔数
    FROM trades_clean
    WHERE status = 'refunded'
    GROUP BY 小时 ORDER BY 退款笔数 DESC
""")

# 两条常用出口：取成 Pandas 或 Arrow
df = rel.df()          # Pandas DataFrame
tbl = rel.arrow()      # Arrow 表（零拷贝，见 5.3）

# 参数化查询：值走占位符，防注入也省拼接
con.execute(
    "SELECT count(*) FROM trades_clean WHERE user_id = ? AND amount > ?",
    [884213, 500.0]
).fetchone()
​

三个细节是工程质量的分水岭。参数化查询永远优于字符串拼接——既是安全习惯，也让执行计划的形状稳定。连接对象的生命周期要与应用一致：长期运行的服务里保持单个连接复用，短脚本里用完即关。结果出口按需选：继续在 Python 里加工就取 DataFrame，数据量大或要跨工具传输就走 Arrow（原因第5.3节展开）。三个细节背后其实是同一条原则：接口层的代码质量体现在"让引擎可预期"——计划形状稳定、连接状态可控、出口与用途匹配，满足这三条，上层应用才敢把关键路径交给嵌入式引擎。

Python 侧还有一个语法糖值得知道：注册替换扫描。把 DataFrame 直接写进 SQL 的 FROM 位置，引擎按名字自动识别——在笔记本里做"SQL 与 Python 混合分析"时最省事，第5.4节实录里会大量使用。用的时候留个心眼：替换扫描读到的是注册那一刻的 DataFrame 视角，变量后来在 Python 侧改了，SQL 侧不会自动跟着变——重新注册或重新执行查询才能看到新值。这个语义在探索期几乎不会踩坑（笔记本习惯就是随时重跑单元格），但在自动化脚本里值得一句注释提醒后来人。

其他语言与分工心法

除 Python 外，官方维护着 Java、R、C++、Rust、Go、Node.js 等一票接口，形态大同小异：开连接、执行、取结果。选型时真正的分叉不在语言，而在形态：

心法一句话：验算用命令行，工程用 API，共享读无所谓、并发写要绕开。主线案例里两条通道都用上了——命令行负责把季度 CSV 批量转 Parquet，Python 负责清洗、聚合与出图，各干各的擅长活。语言侧再补一句选择建议：同一团队尽量收敛到一种语言的接口，命令行做公共底座——多语言并存时，最容易出事的不是接口能力差异，而是各语言的类型映射细节不同（第5.3节的类型保真问题会在每个接口上重演一遍），收敛能把这类坑从"每个语言一份"降到"只有一份"。

关系对象：被低估的中间形态

Python 接口里有个形态值得单独认识：查询返回的不是结果集而是关系对象（relation）——一张还没真正执行的虚拟表。它可以继续链式操作、可以延迟执行、可以随时落地成各种出口：

rel = con.sql("SELECT * FROM trades_clean WHERE status = 'refunded'")

rel.count()          # 行数：此刻才触发执行
rel.project("user_id, amount")   # 继续投影，仍是关系
rel.filter("amount > 500").limit(5)
rel.df()             # 满意了再取成 DataFrame
​

价值在延迟与组合：探索阶段把"基础过滤"固化成关系变量，后续每一步分析都从它出发链式生长——比把中间结果物化成 DataFrame 又快又省，引擎始终掌握优化的全貌（它看到的是一整条查询链，不是多段割裂的 DataFrame 操作）。这个形态还顺手解决了重复执行的问题：同一个关系对象可以反复取出口，执行计划由引擎统一优化。什么时候不用它也有答案——需要 Pandas 独有的变换逻辑时就 .df() 落地，别为了链式好看把所有逻辑硬塞进 SQL。

资源与异常：工程通道的两件防具

正式通道要防两件事。资源泄漏：连接对象、结果集都持有底层资源，长期运行的服务里要注意关闭与复用——连接复用前面讲过，这里补结果集侧：大查询的关系对象用完就放，别在长生命周期对象上挂着几百个未消费的关系。异常处理：SQL 出错抛的是带类型的异常（绑定错、转换错、内存不足各有其类），工程代码里按类型分流处理——类型错记日志报警、内存错触发降级重试、绑定错直接 fail-fast 修代码。把异常当分支逻辑写进程序，是"能跑的脚本"和"敢上线的服务"的分界线。两件防具装好，嵌入式引擎才真正成了应用的一部分——第6.3节的安全边界是第三件防具，那里见。

本节要点回顾

• 命令行是快刀：即席验算、管道组合、格式转换，一条 SQL 转 Parquet 值得背下。
• Python 是正道：参数化查询、连接复用、按需选结果出口，三细节定工程质量。
• 替换扫描是糖：DataFrame 直接进 FROM，笔记本里混合分析最顺手。
• 分工心法：验算行、工程 API、并发写单进程——形态选对比语言选型更重要。