Metabase 查询型 Transforms 完整实战指南：SQL 与查询构建器的定时写回数据管道-北京尧图网络

Metabase 查询型 Transforms 完整实战指南SQL 与查询构建器的定时写回数据管道【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读查询型 TransformQuery-based Transforms是 Metabase 在 Data Studio 中提供的ETL 之 T能力你直接用 SQL 或图形化查询构建器编写一条SELECT查询Metabase 会按计划让数据库执行这条查询、把结果写入一张新的持久化表并同步回 Metabase 供问题Questions、仪表盘和其他 Transform 复用。读完本文你将掌握查询型 Transform 的完整生命周期——从创建、测试、保存配置到利用 SQL 变量与 Snippet 复用查询、配置增量加载与 Merge KeyUpsert再到将模型批量迁移为 Transform并理解其底层执行链路。前置条件查询型 Transform 的可用性与依赖在动手之前需要先确认你的 Metabase 环境满足以下条件Metabase Cloud运行查询型 Transform 需要购买Basic transforms插件add-on。详见 addons.md。自托管 MetabaseBasic transforms即查询型 Transform已包含在自托管版本中Python Transform、Transform Inspector、可写连接writable connections等才需要 Pro/Enterprise 的 Advanced transforms 插件。数据库支持并非所有数据库都支持 Transform。当前支持 BigQuery、ClickHouse仅 ClickHouse Cloud、MySQL/MariaDB、PostgreSQL、Redshift、Snowflake、SQL Server。启用了数据库路由的数据库以及 Metabase 自带的 Sample Database 不支持 Transform。写权限Transform 会在你的数据库中创建并替换表因此连接数据库的用户必须具备 create、drop、write 等相应权限官方建议为数据库配置可写连接Writable connection。启用功能需要先在 Data Studio 中启用 Transforms网格图标 → Data Studio → Transforms按提示启用。从源码看功能的启用是严格受 Premium 特性开关控制的src/metabase/transforms/feature_gating.clj中enabled-source-types仅在premium-features/query-transforms-enabled?为真时把nativeSQL与mbql查询构建器加入可用 source type 集合否则列表为空。这印证了文档中查询型 Transform 需要 Basic transforms 插件的说明。查询型 Transform 的工作原理查询型 Transform 的执行链路非常直观一共五步在 Metabase 中创建一条SELECT查询SQL 或图形化查询构建器Transform 首次运行时由你的数据库执行该查询数据库把查询结果写入一张新表新表被同步sync到 Metabase之后的每次运行数据库会用最新结果覆盖这张表——除非你配置了增量转换。这一点与 Python Transform 有本质区别查询型 Transform 的代码运行在数据库内部而 Python Transform 运行在独立的执行环境Python runner中。源码视角一次查询型 Transform 的执行链路在仓库中查询型 Transform 的调度执行实现在 query_impl.clj 的run-mbql-transform!其关键步骤与文档描述一一对应以归属人身份鉴权执行手动运行以触发者requester身份执行定时cron运行则以 Transform 的 owner无则 creator身份执行执行前通过check-source-query-permissions!校验源查询权限手动运行被拒绝会以 403 返回。防重入通过try-start-unless-already-running登记 run同一 Transform 不会并发运行已运行时会记录 Transform is already running 日志。写连接与执行driver.conn/with-write-connection建立写连接随后调用transforms-base.i/execute-base!真正执行查询并支持取消cancelled?轮询与分阶段计时埋点。后处理complete-execution!负责表同步、事件发布等收尾工作。更底层的查询执行在 query.clj 的run-query-transform!中完成编译查询compile→ 需要时创建 schema → 调用驱动层的driver/run-transform!。它根据目标类型决定执行策略:table普通表每次运行以overwrite? true重建表:table-incremental增量表无 merge key 时追加新行设置了 merge key 时transform-opts返回{:merge {:unique-key ... :columns ...}}执行前会用validate-merge-unique-key!校验 merge key 必须存在于目标列中。创建查询型 Transform完整创建流程如下启用 Transforms。进入Data studio Transforms。点击 New选择来源Query builder用图形化查询构建器写查询SQL写原生 SQLCopy of existing question复制某个已保存问题的查询——注意 Metabase 只复制查询本身之后对原问题的修改不会影响该 Transform。当前不支持在不同 Transform 类型之间互转例如把查询构建器 Transform 转成 SQL Transform。若想更换类型需要以相同的目标表和标签新建 Transform再删除旧的。像平时写查询一样编写你的 Transform 查询。查询构建器用法见 Query builderSQL 编辑器用法见 SQL 编辑器。需注意目标数据库必须支持 Transform。点击编辑器底部的Run按钮测试查询。重要在编辑器中预览查询结果并不会把结果写回数据库可以放心反复调试。点击右上角Save填写 Transform 信息Name必填Transform 名称。Schema必填目标 Schema。可以不同于源表的 Schema直接输入新名称即可创建新 Schema。注意只能在同一个数据库内转换数据不能跨数据库写入。Table name必填目标表名。Metabase 会把结果写入这张表并同步。Folder可选Transform 所在的文件夹点击可切换或新建。Incremental transformation可选是否启用增量转换。可选给 Transform 打标签Tags。标签是 Jobs任务定时调度 Transform 的依据。从实现角度Transform 的目标表信息会被持久化到后端模型 transform.clj执行时由 execute.clj 的execute!将声明式索引indexes挂到 target 上并把full-incremental-run?决策一次性固定下来保证整个运行期间判断稳定。SQL Transform 中的变量与 Snippet 组合复用SQL Transform 支持变量{{my_variable}}但变量只有在与 Snippet 组合时才有实际意义——因为 Transform 是定时运行的无法在运行时弹窗让你输入参数值。典型用法是把一段含变量的完整 SQL 存成 Snippet然后让多个 Transform 各自引用它。官方示例想要按周统计多张表的行数可创建一个名为rows per week的 Snippet内容为SELECT date_trunc(week, created_at) AS week, count(*) AS row_count FROM {{table}} GROUP BY week ORDER BY week这样每个 Transform 的完整 SQL 只需一行{{snippet: rows per week}}然后在每个 Transform 的变量面板中把table的默认值设为各自的目标表如orders、returns、subscriptions。表格类变量Table Variable的用法详见 table variables。这样做的好处是当你需要调整逻辑例如把周粒度改成日粒度只需更新 Snippet 一次所有引用它的 Transform 都会在下次运行时自动生效。变量必须可选或带有默认值Transform 中的参数必须满足以下条件之一用可选块[[ ]]包裹变量或者提供默认值。原因正如文档所述Transform 由 Job 按计划调度执行运行时没有途径向变量传值。这也是 transforms-overview.md 中对 SQL Transform 的硬性要求。运行查询型 Transform手动运行进入Data Studio Transforms打开 Transform 的Runs页点击Run。定时运行先给 Transform 打上标签再创建定时 Job 按标签批量调度。Transform 页面会展示每次运行run的日志与状态。首次运行会创建并同步目标表之后就可以编辑该表的元数据和权限后续运行默认会 drop 并重建表除非启用增量模式。运行记录同样有后端支撑调度执行的统一入口在 execute.clj它通过transforms.i/execute!多方法分发:query类型由 query_impl.clj 实现并在数据库中登记transform_run记录以跟踪状态、支持取消。依赖排序DAG由 dag.clj 与 coordinated_run.clj 负责。增量查询转换Incremental Query Transforms为什么要增量默认情况下除首次运行外每次运行 Metabase 都会处理输入表的全量数据然后 drop 旧目标表、用处理结果创建新表。当数据量很大时这很浪费。将 Transform 标记为增量后Metabase 只处理自上次运行以来新增的数据。增量转换的前提条件数据中必须有一列可供 Metabase 检查新值即Checkpoint检查点列Checkpoint 列的值必须递增如自增 ID 或时间戳Metabase 通过查找大于已写入 checkpoint 值的记录来判断哪些是新增数据Schema 必须稳定即表结构不会随运行而变化。增量查询转换的工作原理配置增量时你需要选择一个检查点列。Metabase 会在后台为你的 Transform 查询自动包裹一层过滤只保留该列值大于上次已写入 checkpoint 值的行。如果你同时设置了 Merge KeyMetabase 会更新匹配该键的目标行而不是追加新行——即实现 Upsert 语义。用表变量实现增量 SQL Transform图形化查询构建器创建的 Transform 可以直接跳过本节去标记为增量。但如果你写的是原生 SQL就必须先把含 checkpoint 列的表替换为表变量。假设原始查询为SELECT orders.id, orders.total, products.title FROM orders JOIN products on orders.product_id products.id想基于orders.id的新值增量加载你需要添加表变量例如{{orders_var}}替换FROM子句中的orders在表变量设置中把orders_var连接到orders表将查询中对orders的其他引用改为表变量名如果变量设置中开启了 Emit table alias或你手写的别名。改造后的查询SELECT orders_var.id, orders_var.total, products.title FROM {{orders_var}} JOIN products on orders_var.product_id products.id这里orders_var在变量设置中连接到orders表并在变量侧栏中开启了 Emit table aliases。查询具备表别名后就可以在 Transform 设置中用orders.id列将其标记为增量。源码印证增量过滤正是注入到表变量上的。src/metabase/transforms_base/util.clj的incremental-table-tag-name会定位与 checkpoint 字段所在表关联的表模板标签把增量范围过滤inject-filters-into-table-tag注入该表变量若增量 SQL Transform 被编辑到丢失表标签会返回 nil 并被视为损坏状态。checkpoint-source?则判断源是否采用 checkpoint 策略full-incremental-run?决定何时需要全量重建首次运行、checkpoint 字段变更、或有待应用的索引变更。标记 Transform 为增量进入Data studio Transforms打开 Transform 页面切换到Settings选项卡在Field to check for new values中选择源表中用于判断新记录的字段仅部分字段符合条件见增量转换前提可选要更新匹配行而不是追加新行可添加 Merge Key。Merge Key 的注意事项Merge Key 引用的是目标表Transform 输出的列而非源表的列如果一条记录需要多列组合才能唯一标识如idregion可同时选择多个列作为 Merge KeyMerge Key 需要一个每次写入行时都会递增的 checkpoint 字段如updated_at否则 Transform 永远感知不到数据变化若目标表已存在可从其列列表中挑选若尚未运行过没有表则需手动输入数据库中的真实列名可能与显示名不同每输入一个按逗号或回车分隔。全量重处理Reprocess all data增量 Transform 运行后Settings页会显示Last processed [checkpoint field]及已写入的最高 checkpoint 值——这正是后续运行断点续传的依据。如需清空该值、全量重建目标表点击Reprocess all data下次运行手动或按计划会从头处理所有行。更换 checkpoint 字段也会重置该值使 Transform 下次运行时全量重建。将模型转换为 Transform如果你有想迁移为 Transform 的模型ModelMetabase 支持批量转换。转换过程中 Metabase 会基于模型的查询创建新 Transform运行 Transform在数据库中生成输出表把所有曾使用该模型的问题、仪表盘及其他内容替换为 Transform 的输出表将原模型转换为一个普通问题。前提必须是管理员且模型的数据库支持 Transform。操作步骤先阅读 Replace data sources替换数据源的概述与限制说明打开Data Studio在侧栏选择Transforms点击Tools Migrate models找到要转换的模型并点击打开详情面板面板会显示模型名称、数据库、所在集合以及依赖它的内容列表点击Convert to a transform填写 Transform 设置同创建查询型 Transform再次点击Convert to a transform确认。Metabase 会在后台执行转换屏幕底部有进度指示。失败与回滚语义若 Transform 运行失败Metabase 会中止并保持模型原样不替换任何内容若 Transform 运行成功但随后的源替换失败Transform 及其输出表会保留模型保持不变你可以用 Replace data sources 手动把剩余内容从模型指向 Transform 输出表转换完成后所有原本查询模型的内容都会改为查询 Transform 输出表原模型退化为普通问题。权限提醒新建的表会使用默认权限不会继承模型的权限。更稳妥的做法是先手动创建并运行 Transform、配置好表权限再用 Replace data sources 把模型替换为 Transform 输出表。常见问题与边界无法跨数据库写入目标 Schema 可以与源不同但源与目标必须在同一数据库内。Transform 类型不可互转查询构建器 ↔ SQL ↔ Python 之间不能直接转换需新建并删除旧对象。编辑定义的影响修改 Transform 查询后下次运行手动或定时即生效若新查询不再输出某个列下游依赖该列的问题会报错。更换目标表在 Settings 的Change target操作中选择保留或删除旧目标表删除不可撤销基于旧目标表构建的问题不会自动迁移到新表。与其他 Transform 的依赖查询型 Transform 可以引用其他 Transform 的目标表也可引用 Metabase 问题和模型。Metabase 会追踪依赖src/metabase/transforms/dag.clj维护 DAG按合理顺序执行若 Transform B 依赖 A 创建的表Metabase 先跑 A 再跑 BJob 运行时会自动补跑尚未更新的依赖。与模型持久化的区别Transform 需要分析师具备 Transform 权限、可自定义目标 Schema/表名、支持的数据库更多、且可用 Python 编写模型持久化未来将被 Transform 取代。延伸阅读Transforms 总览启用、权限、支持的数据库、版本控制与模型对比Jobs 与 Runs标签、定时调度、依赖跳过与失败通知Python TransformsPython 型 Transform 的写法与执行环境Transform Inspector分析数据流、Join 行为与列分布后端实现参考query_impl.clj调度执行、query.clj查询执行与合并策略、util.clj增量/checkpoint/merge 判定【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Metabase 查询型 Transforms 完整实战指南：SQL 与查询构建器的定时写回数据管道

相关推荐

JavaSE I/O体系核心解析：从字节流到序列化的工程实践

2026 AI Agent开发实操路径：Python+LangGraph工程落地指南

Ente Locker 信息类型（Item Types）完全指南：Document、Note、Secret 与 Thing 的存储、加密与最佳实践

更多资讯

基于YOLOv8的红领巾检测实战：从数据标注到OpenVINO部署

2026视频号带货主播榜单分析与运营策略

一文拆解CCF新闻情感分析赛题源码：TextCNN与PyTorch实践指南

LFMCW连续波雷达回波处理全链路解析：差频、距离多普勒与CFAR检测

ProcessHacker 便携版 5 分钟搞定：U 盘里塞进一个不闪退的系统监控

Flow Launcher 快速上手指南：4 个场景把开源启动器变成 Windows 效率工具

今日更新

Linux 内核 ARM 虚拟内存布局全解析：从 4GB 地址空间划分到源码级验证

AIGC降重工具测评与教育应用指南

数据容灾核心指标与实战方案解析

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？