用途
当 DuckDB 是本地分析迭代最快路径时使用本技能。它帮助智能体构建可复现的本地工作流，加速开发，同时避免把原型的便利误认为生产架构。
适用场景包括：
- 在部署到数据仓库之前，本地原型化数据模型与转换
- 用样本数据集复现生产数据问题
- 在开发期间无需远程基础设施即可运行分析查询
- 构建轻量级 CLI 工具、校验器或测试框架
- 使用 dbt-duckdb 适配器本地验证 dbt 模型
- 创建嵌入式分析的概念验证演示
当工作负载需要生产级持久性、并发访问或分布式处理时，不应使用本技能。DuckDB 是开发与原型加速器，不是生产仓库的替代品。
主要能力与工作流
1. 定义本地工作流的目的与范围
需要明确：
- 该工作流要回答或验证什么问题？
- 需要什么样本数据，来自哪里？
- 这是一次性调查还是可重复的开发工作流？
- 如果原型成功，迁移到生产的路径是什么？
2. 设置可复现的数据输入
- 使用签入仓库或由脚本下载的样本文件（CSV、Parquet、JSON）
- 记录样本数据是如何生成或提取的
- 保持样本量具有代表性，同时足够小以便快速迭代
- 利用 DuckDB 直接读取 Parquet、CSV 和 JSON 而无需导入步骤的能力
- 对于敏感数据：仅使用匿名化或合成样本
3. 编写能清晰映射到生产等价物的转换
- 使用可翻译为目标仓库方言的标准 SQL
- 除非工作流永久保持本地，否则避免使用 DuckDB 特有函数
- 按与生产相同的分层模式（staging → intermediate → marts）组织查询
- 使用 dbt-duckdb 时：采用与生产适配器相同的模型结构和测试
- 记录哪些 DuckDB 特有功能在生产中需要替换
4. 用断言与契约检查在本地验证结果
- 运行行数检查、空值断言和键唯一性测试
- 将输出与预期结果或黄金文件比较
- 使用 DuckDB 的 SUMMARIZE 和描述性统计进行快速健全性检查
- 与项目的验证框架集成（Great Expectations、Cuallee 或自定义）
5. 记录生产迁移路径
- 此原型在生产运行前必须改变什么？
- 列出 DuckDB 特有假设：单节点、进程内、基于文件的存储
- 定义目标平台（Snowflake、BigQuery、Redshift、Spark）及方言差异
- 识别需要分布式执行的功能（大规模连接、窗口函数）
- 让迁移成为有意识的决定，而非意外
6. 保持本地工作流可维护
- 包含一个 Makefile 或脚本，可从零开始运行完整本地工作流
- 在 requirements 中固定 DuckDB 版本以防止漂移
- 在运行之间清理临时数据库
- 记录预期执行时间，让开发者知道什么是正常的
- 退役不再有用途的本地工作流
常见合理化借口与事实
| 合理化借口 | 事实 |
|---|---|
| “DuckDB 太快了，我们可以直接在生产中使用。” | DuckDB 是单进程且基于文件的。生产工作负载需要 DuckDB 不提供的并发、持久性和运维工具。 |
| “本地原型基本上和生产一样。” | 本地原型跳过了认证、网络、并发和规模问题。本地与生产之间的差距必须明确记录。 |
| “我们不需要样本数据管理——直接指向生产文件就行。” | 从本地机器指向生产数据会带来安全和规模问题。精心整理的样本更安全、更快速。 |
| “本地能跑，所以仓库里也能跑。” | DuckDB SQL 大体标准，但与 Snowflake、BigQuery 或 Redshift 方言并不完全相同。迁移需要在真实目标上测试。 |
危险信号
- 本地 DuckDB 工作流在没有迁移计划的情况下被当作生产使用
- 样本数据包含真实 PII 或生产机密
- 使用了 DuckDB 特有函数但未记录生产等价物
- 没有 Makefile 或脚本可从零复现工作流
- 本地工作流在笔记本电脑上针对完整生产规模文件运行
- 原型模型未经目标平台验证就部署到生产
- 临时 DuckDB 数据库不断累积而未清理
- DuckDB 版本未固定，导致团队成员之间结果不一致
验证清单
- 本地工作流的目的与范围已记录
- 样本数据可复现、大小适当且不含敏感内容
- SQL 转换使用可映射到目标生产平台的标准模式
- 本地断言与契约检查验证了正确性
- 生产迁移路径已记录，并明确方言差异
- 有 Makefile 或脚本可从干净状态复现完整工作流
- DuckDB 版本已固定且团队内一致
限制
本技能不适用于需要生产级持久性、并发访问或分布式处理的工作负载。DuckDB 是单进程、基于文件的开发与原型加速器，不能替代生产数据仓库。