Metabase 事件与时间线Events and Timelines完全指南把“机构记忆”沉淀到时间序列图表上【免费下载链接】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本指南系统讲解 Metabase 的**事件Events与时间线Timelines**功能如何用“日期 标题 描述 图标”的形式把产品上线、营销活动、宕机等关键节点记录在案并直接叠加到时间序列图表上让团队不必反复追问“三月份那个尖峰到底是什么”。读完本文你将掌握事件与时间线的数据模型与权限机制、在集合与问题Question中的完整操作流程、归档与恢复策略以及背后的 REST API 实现。事件与时间线捕获关于“时间点”的机构知识围绕数据的讨论里几乎总会有一个时刻冒出与某个具体时间点相关的问题“等等三月份的那个尖峰又是什么”“新组件是什么时候上线的”事件与时间线就是用来捕获这种时序知识chronological knowledge并在你需要的时候、在正确的上下文里也就是当你在看图表时把它呈现出来。事件是记录“发生了什么、发生在何时”的机构记忆institutional knowledge的绝佳载体——包括三个月后的你自己在内都不必再去重新推理那条折线图三月份为何飙升。核心概念只有两个事件Event本质上是一个“日期 标题 描述 图标”的组合。你可以往 Metabase 里添加事件让重要的里程碑、产品发布或任何其他事情与你的数据并排展示。时间线Timeline与某个集合Collection关联的一组事件的集合。例如你可以有一条包含重要邮件或销售日期的时间线也可以有一条追踪故障停机时长的“宕机时间线”。两个重要的展示约束来自官方文档Metabase只会在查看单个问题question时把事件显示在时间序列图表上Metabase不会在仪表盘dashboard卡片中的图表上显示事件。时间线的运作机制集合、时间线、事件的三层关系集合可以拥有时间线时间线可以包含事件。落到实际效果上就是你添加到某条时间线的事件会出现在存放在同一集合的时间序列问题上。这是整个功能最核心的一条规则。三条关键行为需要特别记住自动创建默认时间线如果你没有显式创建时间线却直接创建了事件Metabase 会自动为你创建一条时间线作为该集合的默认时间线。一集合多时间线同一个集合可以拥有多条时间线。不向下继承与集合关联的时间线不适用于该集合的子集合sub-collections。从后端数据模型看这一设计由两张应用数据库表支撑。在 src/metabase/timeline/models/timeline.clj 中Timeline模型映射到:timeline表在 src/metabase/timeline/models/timeline_event.clj 中TimelineEvent模型映射到:timeline_event表。二者的字段在 src/metabase/timeline/schema.clj 中有完整的 Malli schema 定义Timeline 表字段id、name、description、icon、collection_id可空空值表示根集合、archived、creator_id、created_at、updated_at、default是否为集合默认时间线、entity_id。TimelineEvent 表字段id、timeline_id外键指向所属时间线、name、description、timestamp、time_matters布尔值、timezone时区、icon、archived、creator_id、created_at、updated_at。其中time_matters是一个值得注意的字段它控制事件的时间匹配精度。在 src/metabase/timeline/db.clj 的timeline-events-for-timelines查询中可以看到当time_matters为true时按timestamp精确到时刻匹配时间范围当time_matters为false时则通过h2x/-date把双方都转成日期后按“天”匹配。关于事件图标TimelineEvent模型定义了可用的枚举见 src/metabase/timeline/models/timeline_event.clj默认图标star星形以及cake、mail、mail_at、warning、bell、cloud、info、note、event。其中mail已标记为 deprecated仅作向后兼容保留曾经存在的balloons图标已被移除对应 issue metabase#34586、metabase#35129读取时会自动回退为默认图标。在集合中查看与添加事件浏览集合时点击右上角的**日历calendar**图标即可查看、添加或编辑该集合的事件。创建事件后只要满足以下条件事件就会出现在集合内的图表上事件的日期落在图表的时间范围内该时间线处于可见状态可见性开关在问题页右下角的日历侧边栏中下文详述。满足条件后你会看到图表 x 轴上出现一个图标来标记事件位置并从事件点延伸出一条垂直线标示图表数据与事件的时间交汇点。一个限制需要留意无法把带事件的时间线添加到数据应用库Library。在查看问题Question时添加事件如果当前问题是一张时间序列图点击问题右下角的**日历Calendar**图标Metabase 会打开时间线侧边栏并列出落在你时间序列范围内的时间线及其事件。在这里你可以切换时间线可见性——包括来自其他集合的时间线添加新事件——即使问题尚未保存也可以添加编辑、移动或归档事件。从实现上看图表页能动态拉取事件得益于/api/timeline系列端点。路由注册位于 src/metabase/api_routes/routes.clj/timeline与/timeline-event两组路由统一挂在认证中间件auth之下。从其他集合的图表上查看并临时应用时间线当你查看一张来自其他集合的问题时间序列图时可以点击问题右下角的日历calendar图标勾选要显示的时间线与事件把该时间线临时应用到当前图表上。需要强调这些选择是临时的。一旦你重新加载问题Metabase 就会把事件从图表上移除——除非你对该图表所在的集合本身拥有那条时间线。如何临时隐藏图表上的时间线及其事件点击右下角的**日历calendar**图标取消勾选相应的时间线或事件。这些选择同样会在重新加载后重置。如果需要永久隐藏某条时间线及其事件只能通过归档时间线实现另一个替代方案是把问题移动到其他集合。编辑事件改标题、换时间线或归档编辑事件的完整步骤点击集合右上角的日历图标进入包含该事件的时间线点击事件旁的三个点菜单...根据需要选择编辑事件Edit event修改其标题、描述与图标移动事件Move event把事件移动到另一条时间线归档事件Archive event将事件从图表上隐藏。“移动事件”在数据层面就是修改timeline_id字段——src/metabase/timeline/api/timeline_event.clj 中的 PUT/:id端点接收timeline_id等更新字段并写入:timeline_event表相应地事件创建端点 POST/也要求timeline_id必须指向一条真实存在的时间线否则返回 404Timeline with id {0} not found。归档时间线与恢复归档是隐藏时间线及其全部事件的正式手段。步骤进入该时间线所属的集合点击右上角的日历图标选择该时间线点击三个点菜单...。如果集合只有一条时间线直接点击三个点菜单...即可选择编辑时间线详情Edit timeline details点击红色的**归档时间线及全部事件Archive timeline and all events**按钮。值得注意的是“归档级联”在服务端是显式实现的在 src/metabase/timeline/api/timeline.clj 的 PUT/:id端点中当archived状态发生变化时会调用set-timeline-events-archived!把该时间线下所有事件的archived标志一并更新。查看已归档的事件和时间线已归档的事件和时间线只能从所属集合中查看它们不会出现在回收站Trash中。查看并可恢复已归档时间线与事件的步骤在相关集合中点击**日历Calendar**图标点击三个点...菜单选择查看已归档时间线View archived timelinesMetabase 会显示已归档的事件或时间线如需恢复点击事件或时间线旁的三个点菜单...选择取消归档Unarchive。要永久删除已归档的事件或时间线点击三个点菜单...并选择删除Delete。随后即可在“查看已归档事件”或“查看已归档时间线”弹窗中完成清理。服务端对应的 DELETE/:id端点见 src/metabase/timeline/api/timeline.clj会级联删除该时间线及其事件返回 204 空响应。事件与时间线的权限体系事件和时间线的权限完全取决于你对集合的权限二者一一对应详见集合权限查看权限View access可以查看集合的事件与时间线也可以把其他集合的时间线和事件临时应用到时间序列图上。整理权限Curate access拥有某集合整理权限的用户可以向该集合添加事件和时间线。从源码层面可以印证这种“继承式”设计Timeline模型派生自:perms/use-parent-collection-perms见 src/metabase/timeline/models/timeline.clj即时间线的权限直接复用其所属集合的权限模型TimelineEvent没有独立的权限集其perms-objects-set实现会把权限判断委托给其所属的 Timeline见 src/metabase/timeline/models/timeline_event.clj事件的创建检查can-create?同样基于所属时间线所在集合的创建权限在 API 层src/metabase/timeline/api/timeline.clj 的创建、更新、删除端点分别调用api/create-check与api/write-check做权限校验集合时间线端点GET/collection/:id则先对集合执行api/read-check列表接口GET/只会返回当前用户可见集合中的时间线其查询逻辑timelines-in-visible-collections在 src/metabase/timeline/db.clj 中通过collection/visible-collection-filter-clause过滤。让所有人可用把时间线建在 All Users 可访问的集合中如果你希望事件和时间线对所有人可见请把它创建在 All Users 组有访问权限的集合中——默认情况下每个用户都属于 All Users 组。但要记住对于该集合之外的问题你只能临时把这些时间线应用到图表上重新加载图表后时间线不会自动出现。进阶通过 REST API 管理时间线与事件除了界面操作时间线模块完整暴露了 REST API便于脚本化运维或二次集成。路由在 src/metabase/api_routes/routes.clj 注册为/api/timeline与/api/timeline-event均为需认证端点。主要端点如下细节见 src/metabase/timeline/api/timeline.clj 与 src/metabase/timeline/api/timeline_event.clj方法路径说明POST/api/timeline创建时间线。name必填icon缺省时为starcollection_id缺省时归入根集合GET/api/timeline列出当前用户可见的时间线支持archivedtrue与includeeventsGET/api/timeline/:id按 ID 获取单条时间线支持includeevents、archived、start、end参数过滤事件PUT/api/timeline/:id更新时间线设置archived会级联归档/取消归档其全部事件DELETE/api/timeline/:id删除时间线并级联删除其事件GET/api/timeline/collection/root获取根集合的时间线GET/api/timeline/collection/:id获取指定集合的时间线POST/api/timeline-event创建事件。name、timestamp、timezone、timeline_id必填可选time_matters、icon、description、source、question_idGET/PUT/DELETE/api/timeline-event/:id按 ID 读取、更新、删除单个事件几个实现层面的细节值得留意事件创建来源事件可以从collections集合界面、question问题界面或直接通过 API 创建。在 src/metabase/timeline/models/timeline_event.clj 的Sourceschema 中仅枚举了collections与question两种来源直接 API 调用则表现为请求体中不带source键创建时会通过 Snowplow 埋点记录来源与关联的问题 ID。时区与时间精度事件创建时timezone为必填字段time_matters决定按精确时刻还是按天匹配时间范围对应 src/metabase/timeline/db.clj 中的查询分支。根集合特殊处理collection_id为nil表示根集合读取时会通过hydrate-root-collection为前端补齐根集合对象见 src/metabase/timeline/api/timeline.clj。审计与通知创建、更新、删除时间线与事件都会通过events/publish-event!发布:event/timeline-create、:event/timeline-update、:event/timeline-delete事件供审计与订阅系统消费。上述行为在仓库测试中均有覆盖例如 test/metabase/timeline/api/timeline_test.clj、test/metabase/timeline/models/timeline_test.clj 与 test/metabase/timeline/models/timeline_event_test.clj可作为你理解接口行为或自行验证时的参考。结语把“为什么”留在图表上事件与时间线是 Metabase 中少有的“低维护、高回报”功能你只需要在关键节点花几秒钟记下“发生了什么、何时发生”此后每个查看该时间序列的人包括未来的你都能立刻读懂数据背后的故事。记住三条要点即可用好它时间线挂在集合上、事件落在时间线里、图表上看到的事件受“时间范围 可见性”双重约束跨集合只能临时叠加永久可见请把时间线建在 All Users 可访问的集合中。如果需要进一步组织你的 Metabase 内容可继续阅读集合Collections与删除与恢复相关文档。【免费下载链接】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），仅供参考