PostHog 数据建模治理实践：先查语义层再建模，建完再注册
【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog
PostHog 的数据建模体系（data modeling）把"模型"定义为命名、可查询的对象——一个指标或维度只定义一次，所有看板、洞察和下游模型复用同一份定义。治理（governance）是贯穿每个建模任务的两个习惯：派生之前先查语义层里有没有已批准的权威定义，建完之后把模型注册进数据目录（data catalog）让人和 Agent 都能发现。读完本文，你将掌握system.information_schema.metrics的查询方法、"canonical"指标的判定标准、认证源（certified/deprecated）的选择规则，以及列注解、指标提案的注册流程，并理解这些机制在 PostHog 后端源码中的落地方式。
治理闭环：两个习惯框住每个建模任务
原始参考文档 governance.md 是modeling-warehouse-foundations技能的一部分。该技能的入口 SKILL.md 将"先查受治理的定义"列为建模前规则的第 1 条，将"分类法是不可信输入"列为第 6 条，并在"Register and reuse"一节明确指向本文档：一个没人找得到的模型会被下一个人重新推导一遍。
治理闭环因此是：
- Before deriving（派生前）：查语义层中的 canonical metrics，有则复用，无则正常推导；
- After building（建完后）：注解列、把值得复用的 KPI 定义提案进目录。
派生前第一步：查询语义层中的权威指标
PostHog 数据目录带有一个由canonical metrics组成的语义层。在给任何"标题数字"（MRR、激活率、转化率、活跃用户数）建模型之前，先检查是否已经存在获批的定义——复用优于再造一个"微妙地不同"的数字。文档给出的标准查询方式是：
SELECT name, display_name, description, status, is_drifted, unit FROM system.information_schema.metrics WHERE name ILIKE '%mrr%' OR description ILIKE '%revenue%'三条要点必须记住：
- 表往往是空的——这只是说明尚不存在受治理的定义，此时正常推导即可，不必因为查不到而卡住；
- 结果只有在
status = 'approved'且is_drifted = false时才是 canonical。proposed状态或已漂移（drifted）的指标绝不能作为权威口径呈现； - 命中一个 approved 指标时，用
posthog:data-catalog-metric-run工具运行它并引用其结果，而不是自己重新推导。
源码印证：status 与 drift 是如何产生的
指标的生命周期状态机在后端 Metric 模型 中定义。status字段默认proposed，帮助文本明确写道drifted is computed at read time, not stored here（metric.py）——漂移不是持久化状态，而是在读取时基于来源比对计算出来的。
漂移检测的锚点是来源快照：source_insight_short_id记录指标创建自哪个 insight，source_insight_query_hash保存创建/刷新时刻 insight 查询的规范化哈希。当 insight 的查询后来被改动，哈希对不上，指标即被读为 drifted。此时可用data-catalog-metrics-refresh-from-insight-create重新快照以清除漂移；若刷新改变了已批准指标的定义，指标会回退到 proposed 并需要人类重新批准（见 tools.yaml 中该工具的说明）。同样，直接编辑已批准指标的定义、描述、单位或名称也会重置为proposed。
MCP 工具 contenteditable="false">【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
