Metabase Legacy Metrics 迁移完全指南理解 v51 指标升级与 Migrated Metrics V1 集合【免费下载链接】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/metabaseMetabase 自版本 51 起对 Metrics指标 功能进行了重大升级。如果你正从 Metabase 50 或更早版本升级所有历史遗留指标Legacy metrics / metrics v1都会被自动迁移为新的 metrics v2 卡片并存放进一个名为Migrated Metrics V1的专用集合中。本文以 docs/data-modeling/legacy-metrics.md 为骨架结合仓库内迁移源码 metrics_v2.clj、custom_migrations.clj 及对应测试 metrics_v2_test.clj带你完整理解这次自动迁移的触发条件、底层实现、迁移后管理员需要做的收尾工作以及新指标模型带来的能力变化。Legacy metricsv1 指标是什么为什么需要升级在 Metabase 51 之前Metabase 中已经存在指标Metrics这一概念它本质上是在某个数据表上保存的一个聚合定义aggregation例如总收入订单数等。这些 v1 指标被存储在应用数据库的metric表中以 JSON 形式保存其definition定义只能挂在某张具体的数据表上无法放入集合collections进行组织与协作也无法像普通问题questions一样被多人共同维护。从版本 51开始Metabase 将指标重构为一种特殊类型的卡片card使其能够存入集合甚至被置顶pinned到集合由具备集合 curate管理权限的任何人编辑在数据浏览器data browser中直接浏览和探索。如果你是从Metabase 50 或更早版本升级而来升级过程中所有现有指标都会被自动迁移到新的 metrics v2 形态迁移产物统一存放在Migrated Metrics V1集合中该集合的 curate 权限仅授予管理员。你可以选择把指标继续留在这个集合里也可以将它们移动到其他集合中继续使用。升级时发生了什么Metrics v1 到 v2 的自动迁移全流程迁移并非复制一份数据这么简单它是一套完整的、可回滚的数据迁移流程。迁移逻辑由自定义 Liquibase 迁移实现代码位于 metrics_v2.clj 的migrate-up!函数其文档注释明确列出了四个步骤创建迁移集合Migrated Metrics V1为每个 v1 指标在迁移集合中创建一个 v2 指标卡片为所有引用了这些指标的问题card备份其dataset_query将这些引用问题中的 v1 指标引用重写为迁移后的 v2 指标卡片。第 1 步创建 Migrated Metrics V1 集合get-or-create-metric-migration-collection-id!负责查找或创建迁移集合其关键属性在源码中写死集合名称Migrated Metrics v1集合 slugmigrated_metrics_v1集合描述This collection and the metrics in it were automatically generated by the migration to v50.由 v50 迁移自动生成值得注意的是源码在创建集合的同时会向All Users所有用户用户组显式插入一条/collection/{collection-id}/read/的读取权限记录。也就是说迁移完成后所有用户都能看到这个集合及其中的指标只读而 curate可编辑权限默认仅管理员组拥有——这与文档中curate access only for admins的表述一致。第 2 步每个 v1 指标转换为一张 v2 指标卡片migrate-up!通过 SQL 将metric表与metabase_table表内连接取出所有 v1 指标然后为每个指标调用create-metric-v2!创建对应的 v2 卡片。convert-metric-v2定义了字段级的转换规则测试 metrics_v2_test.clj 给出了完整的输入输出对照保留原有属性archived、created_at、creator_id、database_id、description、name、table_id将 v1 的definitionJSON 包装成标准的dataset_query形如{:type :query, :database db-id, :query definition}为迁移产物设置新卡片属性type metric、query_type query、display scalar、enable_embedding false、parameters []、parameter_mappings []、visualization_settings {}在description末尾追加(Migrated from metric {id}.)便于识别来源与回滚时解析。其中display scalar意味着迁移后的指标默认以单个数字标量形式展示与 v2 指标无默认维度时显示为单一数值的行为一致。第 3 步重写引用 v1 指标的问题很多现存问题问题卡片可能直接在聚合表达式中引用了 v1 指标例如 MBQL 中的[metric 1]。如果只迁移指标而不改写引用这些问题升级后就会指向不存在的实体。因此migrate-up!会扫描所有dataset_query中包含[metric, %]模式的问题卡片对每个包含指标引用的卡片先在dataset_query_metrics_v2_migration_backup列中备份原始dataset_query回滚用再通过rewrite-metric-consuming-card把 MBQL 聚合表达式里的[metric v1-id]替换为[metric v2-card-id]。metric-ref-id只处理整数 ID 的引用GA metrics with string references are ignored且replace-metric-refs会递归遍历聚合表达式的嵌套结构因此同时引用多个指标、或指标表达式嵌套在:source-query中的情况都能被正确处理——测试 rewrite-multi-metric-consuming-card-test 覆盖了这类场景。此外迁移还顺带在 card.clj 中将这些迁移产生的专用备份列dataset_query_metrics_v2_migration_backup从卡片序列化结果中剔除避免历史遗留字段泄露到 API 响应中。第 4 步回滚机制迁移是双向的metrics-v2迁移通过 custom_migrations.clj 的define-reversible-migration宏注册因此是可逆的。migrate-down!定义了反向流程将dataset_query_metrics_v2_migration_backup IS NOT NULL的卡片恢复为迁移前的dataset_query删除迁移集合中的所有 v2 指标卡片删除 Migrated Metrics V1 集合本身。这套先备份、再改写、可回滚的设计保证了从 v50 及更早版本升级的风险可控。迁移完成后管理员需要做什么升级完成后Migrated Metrics V1 集合会出现在你的 Metabase 中。官方建议的操作非常简单检查迁移产物打开左侧导航栏在Data下找到Metrics即可浏览所有指标包括迁移过来的Migrated Metrics V1 集合中的所有用户均可查看。决定去向指标可以继续留在该集合也可以移动到其他集合。由于 v2 指标支持集合存储与置顶你可以按业务线或团队重新组织它们。按需整理权限该集合 curate 权限仅管理员拥有。如果你希望某个团队自行维护这些指标可以把指标移动到该团队拥有 curate 权限的集合中。Metrics v2 带来了哪些新能力迁移到 v2 之后指标的使用方式与 v1 时代有了本质区别官方文档 Metrics 将其概括为四点任何人都可以创建新指标不再局限于管理员只要拥有对应数据源权限和集合 curate 权限即可指标可以存储并可置顶到集合指标不再是数据表的附属物而是可以像问题、看板一样在集合中组织、置顶甚至可以放入 Library 让查询构建器更突出地展示官方指标拥有集合 curate 权限即可编辑指标对集合有 curate 权限的用户可以编辑该集合中的指标定义且修改定义后所有使用该指标的问题会立即采用新定义可以在数据浏览器中探索指标指标作为一等公民出现在浏览、搜索与命令面板cmd/ctrl k中。新指标的三要素模型v2 指标由三个部分组成详见 Metrics 文档数据源Data source指标绑定在某个具体数据源上只能在基于该数据源的问题中使用数据源可以是表、保存的问题、模型甚至是另一个指标公式Formula即聚合定义必须是对列的聚合如Sum([Price])不能是逐行计算如[Price] [Tax]支持自定义表达式例如 NPS 公式(CountIf([Score] 9) - CountIf([Score] 6)) / Count() * 100也支持引用其他指标维度Dimensions用于分组和筛选指标的可选字段可以人工策展curate哪些字段出现在 Metrics explorer、指标 About 页和看板筛选中并可为时间维度设置默认分组。权限模型因为 v2 指标同时存在于集合、绑定数据源并定义了查询其权限由三部分共同决定详见 Metrics 文档 中的权限表指标操作 \ 所需权限View dataCreate queriesCollection创建或编辑定义非 Blocked至少 Query builderCurate查看非 Blocked任意View在查询构建器中使用非 Blocked至少 Query builderView也就是说只要用户拥有集合 curate 权限与数据源上Create queries权限就能在该集合中创建、编辑指标。源码与测试迁移实现的可验证依据如果你希望深入验证迁移行为仓库中提供了完整的实现与测试迁移主体metrics_v2.cljmigrate-up!/migrate-down!、convert-metric-v2、rewrite-metric-consuming-card迁移注册框架custom_migrations.cljdefine-reversible-migration宏Liquibase 自定义迁移迁移测试metrics_v2_test.clj 与 metrics_v2_batch_test.clj前者覆盖了基础指标转换、指标引用大小写metric/METRIC/meTriC与多指标引用重写等场景迁移产物字段处理card.clj剔除备份列、指标卡片序列化与维度关联逻辑。迁移相关的注意事项与限制只迁移一次产物是副本而非覆盖v1 指标被转换为 v2 卡片后迁移集合中的卡片是可独立编辑的正式指标。建议在升级前做好应用数据库备份参见 backing-up-metabase-application-data。指标仍绑定数据源即便是 v2指标依然只在其定义的数据源上可用无法跨数据源使用包括由原数据源派生的数据源。仅限查询构建器指标只在查询构建器Query Builder中可用如果你需要可复用的 SQL 片段应使用 SQL Snippets。无法限制创建无法阻止用户在他们已有查询权限的数据源上创建指标。迁移集合建议人工复核虽然迁移逻辑经过测试覆盖但从 v50 及更早版本升级后仍建议管理员抽查 Migrated Metrics V1 集合中的指标定义与原始指标是否一致再决定移动或整理。延伸阅读Metrics新指标模型新指标的完整使用指南创建、编辑、维度策展、缓存、验证等Models模型与指标互补的复用数据层Segments分段行级过滤的复用定义Library资料库将指标置入 Library 以突出展示官方口径Measures度量与指标配合的数值计算定义SQL Snippets可复用的 SQL 片段方案Collection permissions 与 Data permissions理解指标权限的底层模型【免费下载链接】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），仅供参考