尧图网页设计 
本系列基于 SQLMesh 官方文档整理讲三种不走常规计算路径的模型类型每篇一种第一篇EMBEDDED —— 不产生任何表/视图逻辑内联进下游查询第二篇EXTERNAL —— 只登记外部表的列信息模型本身不会被运行第三篇MANAGED本篇—— 数据由数据库引擎的后台进程自动保持最新主要参考Managed modelshttps://sqlmesh.readthedocs.io/en/stable/concepts/models/managed_models/Model kindshttps://sqlmesh.readthedocs.io/en/stable/concepts/models/model_kinds/一、它解决什么问题常规表需要你自己负责数据更新。但有些引擎支持一种引擎自己保证表内数据是最新的的表它基于一个读取其他表的查询构建一旦被读的基表发生变化数据库就自动让这张托管表反映这些变化用户不需要做任何额外操作尤其不需要手动发REFRESH。官方描述其底层机制“most of them have background processes that run and automatically keep the tables up to date, within the parameters you define when you create the table.”MANAGED模型就是把这种引擎能力暴露给 SQLMesh其含义是This indicates to SQLMesh that the underlying database engine will ensure that the data remains up to date and all SQLMesh needs to do is maintain the schema.即引擎负责数据新鲜度SQLMesh 只负责维护 schema。官方 Model kinds 页同时给出行为差异These models don’t get updated with new intervals or refreshed whensqlmesh runis called. Responsibility for keeping thedataup to date falls on the engine.也就是说调用sqlmesh run时MANAGED 模型不会按新时间区间被增量计算也不会被刷新。二、与物化视图的区别必考点SQLMesh 早就支持物化视图kind VIEW ( materialized true )那为什么还需要 MANAGED差别在语义且在部分引擎下两者其实没有区别。物化视图的局限依引擎而定查询通常只能派生自单个基表引擎不会自动维护需要手动发REFRESH MATERIALIZED VIEW或等价命令才能刷新数据。MANAGED 模型的三点不同基表变化时引擎自动更新表数据更新时引擎对查询具备语义理解能自行判断该做增量刷新还是全量刷新无需手动REFRESH引擎在后台进程透明维护。顺带回顾SQLMesh 的VIEW若设materialized true仅对支持物化视图的引擎生效BigQuery、Databricks、Snowflake且只有当渲染出的查询与上次建视图时的查询不一致、或目标视图不存在时才会重建。三、最关键的实践结论应当基于 EXTERNAL 模型构建本系列前两篇在这里闭环了。官方原文“managed models would typically be built off an External Model rather than another SQLMesh model.”理由讲得很直白“Since SQLMesh already ensures that models it’s tracking are kept up to date, the main benefit of managed models comes when they read from external tables that aren’t tracked by SQLMesh.”拆开理解SQLMesh 已经在保证它自己跟踪的模型是最新的你再套一层引擎托管属于重复劳动MANAGED 的真正收益出现在读取 SQLMesh 不跟踪的外部表时——外部表一直在变而你需要一张永远跟得上它的表这时让引擎后台刷新来做最合适。于是三篇串成一条完整的常见链路外部系统表 │ ├─ EXTERNAL第 2 篇登记列信息 → 打通列级血缘、类型推断、上游审计 │ ├─ MANAGED本篇读取它 → 引擎自动保持数据新鲜无需自己调度 │ └─ 常规 SQLMesh 模型FULL / INCREMENTAL_BY_TIME_RANGE …做正式加工四、支持情况与写法示例⚠️前提警告官方原文置于页面顶部“Managed models are still under development and the API / semantics may change as support for more engines is added”即仍在开发中随着更多引擎接入API 与语义可能变化。当前实现的引擎引擎底层实现SnowflakeDynamic Table其余引擎暂未实现——这正是下文可移植性差的直接原因。4.1 完整示例Snowflake Dynamic Table模型定义MODEL(name db.events,kind MANAGED,physical_properties(warehousedatalake,target_lag2 minutes,data_retention_time_in_days2));SELECTevent_date::DATEasevent_date,event_payload::TEXTaspayloadFROMraw_eventsSQLMesh 实际下发到引擎的命令CREATEORREPLACEDYNAMICTABLEdb.events WAREHOUSEdatalake,TARGET_LAG2 minutesDATA_RETENTION_TIME_IN_DAYS2ASSELECTevent_date::DATEasevent_date,event_payload::TEXTaspayloadFROMraw_events4.2 务必注意不要加时间过滤的 WHERE官方专门加了 Note“SQLMesh will not create intervals and run this model for each interval, so there is no need to add a WHERE clause with date filters like you would for a normal incremental model. How the data in this model is refreshed is completely up to Snowflake.”新手最容易犯的错就是照抄增量模型写法加上WHERE event_date BETWEEN start_ds AND end_ds——MANAGED 不需要也不该这么写。4.3physical_properties与引擎参数由于没有统一标准各厂商实现、语义、配置参数都不同SQLMesh 通过physical_properties把引擎专属参数透传给适配器官方说明见 Model kinds 页与模型概览页的 physical_properties。Snowflake Dynamic Table 中以下属性设在模型的physical_properties上Snowflake 属性是否必填说明target_lag必填数据新鲜度目标warehouse否Snowflake 侧本是必填项若不在 SQLMesh 指定SQLMesh 会取select current_warehouse()的结果refresh_mode否刷新模式initialize否初始数据何时填充data_retention_time_in_days否数据保留天数max_data_extension_time_in_days否最大数据延展天数另有属性直接写在模型顶层而非physical_propertiesSnowflake 属性写法CLUSTER BYclustered_by是标准模型属性直接在模型上设置clustered_by即可为 Dynamic Table 加上CLUSTER BY子句完整属性清单见 Snowflake 的CREATE DYNAMIC TABLE文档。五、生命周期仍享受 SQLMesh 治理能力MANAGED 模型遵循与其他模型相同的生命周期这是它仍值得用的重要原因创建虚拟环境 生成指向当前模型快照的指针修改模型 → 产生新快照上游变更 → 产生新快照可通过常规的**指针交换pointer swap**机制部署与回滚TTL 过期后快照被清理。所以官方说法是即便需要用 Managed 模型你依然保有 SQLMesh 的其他收益例如在虚拟环境中使用它。⚠️ 一个必须知道的风险dev 预览用的是普通表因为托管表通常有厂商附加成本官方举例Snowflake 对 Dynamic Tables 有额外费用SQLMesh尽量避免不必要地创建托管表“in forward-only plans we just create a normal table to preview the changes and only re-create the managed table on deployment to prod.”即 forward-only plan 场景下dev 环境预览变更时只建一张普通表直到部署到 prod 才真正重建为 managed 表。官方由此给出 Warning“Due to the use of normal tables for dev previews, it is possible to write a query that uses features that are available to normal tables in the target engine but not managed tables. This could result in a scenario where a plan works in a dev environment but fails when deployed to production.”翻译成人话你可能写出一个普通表支持、但托管表不支持的查询导致 plan 在 dev 一切正常、部署到生产才失败。官方认为这点代价值得但如果给你造成困扰欢迎去反馈。实践对策涉及 MANAGED 的变更不要把 dev 验证通过当成最终结论生产发布窗口要重点复核上线前对照引擎的 Dynamic Table 支持范围自查查询语法保留一条降级为常规模型的回退方案比如等价的INCREMENTAL_BY_TIME_RANGE版本生产失败时可快速切回。六、适用与不适用清单适合需要持续反映外部/非 SQLMesh 跟踪源表的数据且引擎原生支持自动维护想省掉调度负担——不必自己的批处理作业反复刷这张表对数据新鲜度有明确 SLA用target_lag表达且能接受厂商额外费用同时希望保留 SQLMesh 的版本、部署、回滚、虚拟环境等治理能力。不适合 / 应谨慎可移植性差是首要顾虑官方明确“MANAGED models are not as portable between database engines as other SQLMesh model types”因为没有标准各厂商语义与参数都不同。若项目有多引擎迁移可能慎用状态可见性受限官方指出“due to their black-box nature, SQLMesh has limited visibility into the integrity and state of the model”——黑盒性质导致 SQLMesh 对该模型的完整性与状态了解有限数据质量保障弱于自己计算落表的模型官方默认建议“We would recommend using standard SQLMesh model types in the first instance.”优先用标准类型确实需要才用 MANAGED仍在开发中API/语义可能变化Python 模型不支持MANAGED官方 Note须改用 SQL 模型。七、三种类型终极对照把本系列三篇收在一张表上维度EMBEDDEDEXTERNALMANAGED本质可复用 SQL 片段编译期内联外部表的元数据登记引擎托管的表数仓里有对象吗❌ 无表无视图❌ 无表本来就在外面✅ 有引擎建的托管表谁维护数据不适用不落地外部系统数据库引擎的后台进程sqlmesh run会计算它吗❌ 不会❌ 没有可运行的查询❌ 不按区间增量/刷新定义位置models/*.sql根目录external_models.yaml/external_models/*.yamlmodels/*.sqlkind 专属参数无YAML 字段name/description/gateway/columns/audits靠physical_properties透传引擎参数主要收益复用逻辑、零对象膨胀列级血缘、类型推断、上游审计免调度、自动新鲜度、仍可用虚拟环境主要风险逻辑重/引用多时成本随下游增长YAML 与实际表结构漂移可移植性差、状态黑盒、厂商成本、dev/prod 校验差异Python 模型支持❌不适用❌选型口诀逻辑要复用但不想在数仓里多一个对象→EMBEDDED表不归 SQLMesh 管、只是要读它→EXTERNAL登记列信息顺手加上审计表要由引擎负责保持新鲜且读的是不受 SQLMesh 管理的外部表 →MANAGED先确认引擎已支持需要自己定义计算逻辑并按节奏刷新→ 老实用最基础的三类小表FULL、事件/日志/交易INCREMENTAL_BY_TIME_RANGE、有主键要 upsert 用INCREMENTAL_BY_UNIQUE_KEY。八、小结MANAGED 把计算与刷新的控制权交给引擎SQLMesh只维护 schema它与物化视图的差别在于跨多基表、引擎有语义理解、无需手动 REFRESH最佳搭档是 EXTERNAL——读不受 SQLMesh 跟踪的外部表才是它的价值所在仍享有快照、指针交换、回滚、虚拟环境等治理能力三大代价可移植性差、状态黑盒、厂商额外成本以及dev 用普通表预览可能导致生产才失败官方立场优先用标准模型类型确有需要再用 MANAGED。回到入门系列那条一以贯之的心法——SQLMesh 的能力来自它掌握模型的计算方式和状态EMBEDDED 放弃独立资产换取代码复用EXTERNAL 放弃数据控制权换取血缘与质量可见性MANAGED 放弃计算控制权换取免调度的新鲜度代价是可见性与可移植性下降。理解了这组控制权 vs 收益的权衡这三种特殊类型就再也不会选错了。参考资料SQLMesh 官方文档 — Managed models、Model kinds、Model configuration SQLMesh 模型类型详解（三）：MANAGED——把数据刷新外包给引擎
本系列基于 SQLMesh 官方文档整理讲三种不走常规计算路径的模型类型每篇一种第一篇EMBEDDED —— 不产生任何表/视图逻辑内联进下游查询第二篇EXTERNAL —— 只登记外部表的列信息模型本身不会被运行第三篇MANAGED本篇—— 数据由数据库引擎的后台进程自动保持最新主要参考Managed modelshttps://sqlmesh.readthedocs.io/en/stable/concepts/models/managed_models/Model kindshttps://sqlmesh.readthedocs.io/en/stable/concepts/models/model_kinds/一、它解决什么问题常规表需要你自己负责数据更新。但有些引擎支持一种引擎自己保证表内数据是最新的的表它基于一个读取其他表的查询构建一旦被读的基表发生变化数据库就自动让这张托管表反映这些变化用户不需要做任何额外操作尤其不需要手动发REFRESH。官方描述其底层机制“most of them have background processes that run and automatically keep the tables up to date, within the parameters you define when you create the table.”MANAGED模型就是把这种引擎能力暴露给 SQLMesh其含义是This indicates to SQLMesh that the underlying database engine will ensure that the data remains up to date and all SQLMesh needs to do is maintain the schema.即引擎负责数据新鲜度SQLMesh 只负责维护 schema。官方 Model kinds 页同时给出行为差异These models don’t get updated with new intervals or refreshed whensqlmesh runis called. Responsibility for keeping thedataup to date falls on the engine.也就是说调用sqlmesh run时MANAGED 模型不会按新时间区间被增量计算也不会被刷新。二、与物化视图的区别必考点SQLMesh 早就支持物化视图kind VIEW ( materialized true )那为什么还需要 MANAGED差别在语义且在部分引擎下两者其实没有区别。物化视图的局限依引擎而定查询通常只能派生自单个基表引擎不会自动维护需要手动发REFRESH MATERIALIZED VIEW或等价命令才能刷新数据。MANAGED 模型的三点不同基表变化时引擎自动更新表数据更新时引擎对查询具备语义理解能自行判断该做增量刷新还是全量刷新无需手动REFRESH引擎在后台进程透明维护。顺带回顾SQLMesh 的VIEW若设materialized true仅对支持物化视图的引擎生效BigQuery、Databricks、Snowflake且只有当渲染出的查询与上次建视图时的查询不一致、或目标视图不存在时才会重建。三、最关键的实践结论应当基于 EXTERNAL 模型构建本系列前两篇在这里闭环了。官方原文“managed models would typically be built off an External Model rather than another SQLMesh model.”理由讲得很直白“Since SQLMesh already ensures that models it’s tracking are kept up to date, the main benefit of managed models comes when they read from external tables that aren’t tracked by SQLMesh.”拆开理解SQLMesh 已经在保证它自己跟踪的模型是最新的你再套一层引擎托管属于重复劳动MANAGED 的真正收益出现在读取 SQLMesh 不跟踪的外部表时——外部表一直在变而你需要一张永远跟得上它的表这时让引擎后台刷新来做最合适。于是三篇串成一条完整的常见链路外部系统表 │ ├─ EXTERNAL第 2 篇登记列信息 → 打通列级血缘、类型推断、上游审计 │ ├─ MANAGED本篇读取它 → 引擎自动保持数据新鲜无需自己调度 │ └─ 常规 SQLMesh 模型FULL / INCREMENTAL_BY_TIME_RANGE …做正式加工四、支持情况与写法示例⚠️前提警告官方原文置于页面顶部“Managed models are still under development and the API / semantics may change as support for more engines is added”即仍在开发中随着更多引擎接入API 与语义可能变化。当前实现的引擎引擎底层实现SnowflakeDynamic Table其余引擎暂未实现——这正是下文可移植性差的直接原因。4.1 完整示例Snowflake Dynamic Table模型定义MODEL(name db.events,kind MANAGED,physical_properties(warehousedatalake,target_lag2 minutes,data_retention_time_in_days2));SELECTevent_date::DATEasevent_date,event_payload::TEXTaspayloadFROMraw_eventsSQLMesh 实际下发到引擎的命令CREATEORREPLACEDYNAMICTABLEdb.events WAREHOUSEdatalake,TARGET_LAG2 minutesDATA_RETENTION_TIME_IN_DAYS2ASSELECTevent_date::DATEasevent_date,event_payload::TEXTaspayloadFROMraw_events4.2 务必注意不要加时间过滤的 WHERE官方专门加了 Note“SQLMesh will not create intervals and run this model for each interval, so there is no need to add a WHERE clause with date filters like you would for a normal incremental model. How the data in this model is refreshed is completely up to Snowflake.”新手最容易犯的错就是照抄增量模型写法加上WHERE event_date BETWEEN start_ds AND end_ds——MANAGED 不需要也不该这么写。4.3physical_properties与引擎参数由于没有统一标准各厂商实现、语义、配置参数都不同SQLMesh 通过physical_properties把引擎专属参数透传给适配器官方说明见 Model kinds 页与模型概览页的 physical_properties。Snowflake Dynamic Table 中以下属性设在模型的physical_properties上Snowflake 属性是否必填说明target_lag必填数据新鲜度目标warehouse否Snowflake 侧本是必填项若不在 SQLMesh 指定SQLMesh 会取select current_warehouse()的结果refresh_mode否刷新模式initialize否初始数据何时填充data_retention_time_in_days否数据保留天数max_data_extension_time_in_days否最大数据延展天数另有属性直接写在模型顶层而非physical_propertiesSnowflake 属性写法CLUSTER BYclustered_by是标准模型属性直接在模型上设置clustered_by即可为 Dynamic Table 加上CLUSTER BY子句完整属性清单见 Snowflake 的CREATE DYNAMIC TABLE文档。五、生命周期仍享受 SQLMesh 治理能力MANAGED 模型遵循与其他模型相同的生命周期这是它仍值得用的重要原因创建虚拟环境 生成指向当前模型快照的指针修改模型 → 产生新快照上游变更 → 产生新快照可通过常规的**指针交换pointer swap**机制部署与回滚TTL 过期后快照被清理。所以官方说法是即便需要用 Managed 模型你依然保有 SQLMesh 的其他收益例如在虚拟环境中使用它。⚠️ 一个必须知道的风险dev 预览用的是普通表因为托管表通常有厂商附加成本官方举例Snowflake 对 Dynamic Tables 有额外费用SQLMesh尽量避免不必要地创建托管表“in forward-only plans we just create a normal table to preview the changes and only re-create the managed table on deployment to prod.”即 forward-only plan 场景下dev 环境预览变更时只建一张普通表直到部署到 prod 才真正重建为 managed 表。官方由此给出 Warning“Due to the use of normal tables for dev previews, it is possible to write a query that uses features that are available to normal tables in the target engine but not managed tables. This could result in a scenario where a plan works in a dev environment but fails when deployed to production.”翻译成人话你可能写出一个普通表支持、但托管表不支持的查询导致 plan 在 dev 一切正常、部署到生产才失败。官方认为这点代价值得但如果给你造成困扰欢迎去反馈。实践对策涉及 MANAGED 的变更不要把 dev 验证通过当成最终结论生产发布窗口要重点复核上线前对照引擎的 Dynamic Table 支持范围自查查询语法保留一条降级为常规模型的回退方案比如等价的INCREMENTAL_BY_TIME_RANGE版本生产失败时可快速切回。六、适用与不适用清单适合需要持续反映外部/非 SQLMesh 跟踪源表的数据且引擎原生支持自动维护想省掉调度负担——不必自己的批处理作业反复刷这张表对数据新鲜度有明确 SLA用target_lag表达且能接受厂商额外费用同时希望保留 SQLMesh 的版本、部署、回滚、虚拟环境等治理能力。不适合 / 应谨慎可移植性差是首要顾虑官方明确“MANAGED models are not as portable between database engines as other SQLMesh model types”因为没有标准各厂商语义与参数都不同。若项目有多引擎迁移可能慎用状态可见性受限官方指出“due to their black-box nature, SQLMesh has limited visibility into the integrity and state of the model”——黑盒性质导致 SQLMesh 对该模型的完整性与状态了解有限数据质量保障弱于自己计算落表的模型官方默认建议“We would recommend using standard SQLMesh model types in the first instance.”优先用标准类型确实需要才用 MANAGED仍在开发中API/语义可能变化Python 模型不支持MANAGED官方 Note须改用 SQL 模型。七、三种类型终极对照把本系列三篇收在一张表上维度EMBEDDEDEXTERNALMANAGED本质可复用 SQL 片段编译期内联外部表的元数据登记引擎托管的表数仓里有对象吗❌ 无表无视图❌ 无表本来就在外面✅ 有引擎建的托管表谁维护数据不适用不落地外部系统数据库引擎的后台进程sqlmesh run会计算它吗❌ 不会❌ 没有可运行的查询❌ 不按区间增量/刷新定义位置models/*.sql根目录external_models.yaml/external_models/*.yamlmodels/*.sqlkind 专属参数无YAML 字段name/description/gateway/columns/audits靠physical_properties透传引擎参数主要收益复用逻辑、零对象膨胀列级血缘、类型推断、上游审计免调度、自动新鲜度、仍可用虚拟环境主要风险逻辑重/引用多时成本随下游增长YAML 与实际表结构漂移可移植性差、状态黑盒、厂商成本、dev/prod 校验差异Python 模型支持❌不适用❌选型口诀逻辑要复用但不想在数仓里多一个对象→EMBEDDED表不归 SQLMesh 管、只是要读它→EXTERNAL登记列信息顺手加上审计表要由引擎负责保持新鲜且读的是不受 SQLMesh 管理的外部表 →MANAGED先确认引擎已支持需要自己定义计算逻辑并按节奏刷新→ 老实用最基础的三类小表FULL、事件/日志/交易INCREMENTAL_BY_TIME_RANGE、有主键要 upsert 用INCREMENTAL_BY_UNIQUE_KEY。八、小结MANAGED 把计算与刷新的控制权交给引擎SQLMesh只维护 schema它与物化视图的差别在于跨多基表、引擎有语义理解、无需手动 REFRESH最佳搭档是 EXTERNAL——读不受 SQLMesh 跟踪的外部表才是它的价值所在仍享有快照、指针交换、回滚、虚拟环境等治理能力三大代价可移植性差、状态黑盒、厂商额外成本以及dev 用普通表预览可能导致生产才失败官方立场优先用标准模型类型确有需要再用 MANAGED。回到入门系列那条一以贯之的心法——SQLMesh 的能力来自它掌握模型的计算方式和状态EMBEDDED 放弃独立资产换取代码复用EXTERNAL 放弃数据控制权换取血缘与质量可见性MANAGED 放弃计算控制权换取免调度的新鲜度代价是可见性与可移植性下降。理解了这组控制权 vs 收益的权衡这三种特殊类型就再也不会选错了。参考资料SQLMesh 官方文档 — Managed models、Model kinds、Model configuration