migrating-sql-to-dbt

用途：把存储过程、视图或原始 SQL 文件迁移为模块化的 dbt 模型，按层逐步转换并验证，而非一次性整体转换。\n\n主要能力与流程：1) 分析旧 SQL，使用 cat <legacy_sql_file> 读取文件并识别引用的所有表。2) 检查已有资产，用 grep -r "<table_name>" models/ --include=".sql" --include=".yml" 与 find models/ -name "*.sql" | xargs grep -l "<table_name>" 搜索已有模型或 source；若某表既无模型也无 source，需询问用户是否创建为 source，所有依赖就绪后才进入中间层与 mart 层。3) 在 models/staging/sources.yml 中用 version: 2 与 sources 定义缺失的 source，含 name、schema、tables 及 description。4) 建 staging 层，每个源表对应一个 staging 模型，遵循项目命名规范，并用 dbt build --select <staging_model> 先构建。5) 按需建 intermediate 层，把复杂 join 与逻辑抽离，用 dbt build --select <intermediate_model> 增量构建。6) 建 mart 层，作为面向业务的最终聚合模型。7) 验证迁移，执行 dbt build --select +<final_model> 与 dbt show --select <final_model>，并人工核对行数。\n\n检查清单：源表已识别记录、sources.yml 含描述、staging 与源 1:1 且列已重命名、intermediate 已抽离业务逻辑、mart 完成最终聚合、每层编译与构建成功、行数与原结果一致、关键约束已加测试。\n\n常见模式：嵌套子查询拆为独立模型（staging→intermediate→mart）；临时表用 {{ config(materialized='ephemeral') }} 物化；硬编码值改为 {{ var("name") }} 变量。\n\n反模式：把整个旧查询塞入单个 dbt 模型、跳过 staging 层、未逐层验证、保留硬编码值、迁移时不做业务逻辑记录。\n\n限制：资料未提供适用 dbt 版本、支持的数据库平台、性能或成本相关信息，暂未提供；行数一致性等需人工验证。