Notion 与 Snowflake / BigQuery / dbt 企业级数仓指标回写与数据血缘(Data Lineage)治理实战:从 Reverse ETL 定时同步、指标口径字典到 Formula 2.0 SLA 新鲜度监控闭环
一、为什么数据团队要用 Notion 承接 Snowflake / BigQuery / dbt 的指标字典与 Reverse ETL? #
在现代数据工程实践中,数据团队通常在 Snowflake 或 Google BigQuery 中存储 PB 级明细数据,并利用 dbt(data build tool) 管理 SQL 模型转换与单元测试。然而,业务部门在使用数据看板时仍然频繁遭遇两大困境:
- 技术文档与业务口径长期分裂:dbt 自带的
dbt docs静态站点偏重表字段(Schema)与有向无环图(DAG),产品、运营与财务负责人很少打开开发者站点查看口径说明,导致“净 GMV 是否剔除退款与运费”等基础问题反复在群里扯皮。 - 核心指标无法直达业务日常决策区:管理层日常审批 OKR 与项目复盘都在 Notion 中完成,如果每次核对周活(WAU)、留存率或渠道 CAC 都要重新登录 BI 工具导出截图,不仅信息滞后,也无法通过自动化规则触发预警。
将 dbt 元数据血缘 与 Reverse ETL(反向数据同步) 机制接入 Notion 后,既能让 Notion 充当非技术人员可读的统一指标词典,又能将经数仓加工的权威 KPI 定时回写至经营台账(完整数据栈对比请参阅 Notion 与现代数据栈及 BI 可视化中枢实战 与 数据库性能调优与瘦身手册)。
| 平台组件 | Snowflake / BigQuery(云数仓) | dbt(转换与血缘编排) | Notion 数据治理与 KPI 中枢 |
|---|---|---|---|
| 核心职责 | 海量明细存储、MPP 分布式聚合与权限隔离 | SQL 模块化建模、Schema 测试与模型血缘生成 | 业务口径定义、指标 Owner 问责、Reverse ETL 指标呈现 |
| 受众角色 | 数据工程师、ETL 调度系统 | 分析工程师(Analytics Engineer) | 业务负责人、产品经理、高管与跨部门协作者 |
| 更新频率与成本 | 按查询扫描量(TB)或计算节点(Credit)计费 | CI/CD 或 Airflow/Dagster 定时调度构建 | 仅接收聚合后结果(如按日/按周 KPI),零高并发明细压力 |
| 血缘与变更感知 | INFORMATION_SCHEMA 记录物理表变更 | manifest.json 精确输出上游依赖与测试状态 | 通过 Relation 关联上游模型并在模型更名时告警 |
二、企业级指标字典与血缘追踪三表数据库架构 #
严禁直接把百万级订单流水同步进 Notion!正确做法是在数仓侧完成 GROUP BY 聚合,并在 Notion 中构建“指标口径词典 + dbt 物理模型表 + 定时同步批次日志”三表架构(属性设计与关联方法详见 数据库属性全解 与 关系和汇总官方指南):
| 数据库名称 | 核心字段(属性名与类型) | 治理规则与同步机制 |
|---|---|---|
DB_Metric_Catalog(企业指标字典) | 指标唯一键 (Title,如 kpi_net_mrr_usd)、中文名称 (Text)、业务口径说明 (Text)、当前最新值 (Number)、上期对比值 (Number)、指标单位 (Select: USD/CNY/%/人)、关联上游模型 (Relation -> DB_Dbt_Models)、SLA_小时上限 (Number,如 26)、环比波动阈值_Pct (Number)、最后同步时间 (Date)、业务负责人 (Person)、健康状态门禁 (Formula 2.0) | 业务口头确认的新增指标必须先在此建档并指定 指标唯一键;脚本仅回写数值与时间戳,不覆盖人工维护的口径说明 |
DB_Dbt_Models(数仓模型血缘台账) | dbt_unique_id (Title,如 model.dw.fct_orders)、数仓层级 (Select: Staging/Intermediate/Mart)、物理表路径 (Text)、最近构建状态 (Select: Pass/Warn/Fail/Deprecated)、上游依赖数 (Number)、最近测试通过率 (Number) | 由 CI/CD 每次执行 dbt build 后自动解析 target/manifest.json 与 run_results.json 刷新 |
DB_Sync_Runs(Reverse ETL 审计日志) | 调度流水号 (Title)、关联指标 (Relation -> DB_Metric_Catalog)、扫描行数 (Number)、查询耗时_s (Number)、写入状态 (Select: Success/Partial/Failed)、异常摘要 (Text) | 记录每次 Reverse ETL 的运行现场,防止静默断流导致高管看到过期数周的假数据 |
三、五步落地 dbt Manifest 血缘同步与 Reverse ETL 指标回写(Python) #
按照以下五步即可构建低成本、可观测的数仓至 Notion 回写管道(Notion 集成密钥申请请参阅 创建 Notion API 集成指南):
- 在 Snowflake / BigQuery 中建立专供 Reverse ETL 的视图层:创建独立 Schema(如
ANALYTICS_EXPORT.NOTION_KPI_SNAPSHOT),采用静态字段名输出metric_key、current_value、previous_value与as_of_timestamp,避免底层宽表增减列影响导出契约。 - 提取
dbt血缘与构建产物:在 Airflow、GitHub Actions 或 Dagster 任务末尾读取target/manifest.json与target/run_results.json,校验目标 Mart 模型当日的unique、not_null测试是否全部通过;若上游测试失败,立即熔断指标回写,并仅更新DB_Dbt_Models状态为Fail。 - 显式处理高精度浮点(
Decimal/BIGNUMERIC)与时间精度:Snowflake 的NUMBER(38,6)与 BigQuery 的NUMERIC在 Python 中默认返回Decimal对象,JSON 序列化会直接报错;回写 NotionNumber属性前必须显式转换为四舍五入后的float(如保留 2~4 位小数)。 - 部署含指数退避与幂等 Upsert 的 Python 回写脚本(限流控制机制详见 Notion API 速率限制与容错实战):
import os
import time
import json
from decimal import Decimal
import requests
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
METRIC_DB_ID = os.environ["METRIC_DB_ID"]
HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2022-06-28",
"Content-Type": "application/json",
}
def notion_request(method, url, payload=None):
for attempt in range(4):
resp = requests.request(method, url, headers=HEADERS, json=payload, timeout=20)
if resp.status_code == 429:
wait_sec = int(resp.headers.get("Retry-After", 2))
time.sleep(wait_sec)
continue
resp.raise_for_status()
return resp.json()
raise RuntimeError("Exceeded Notion API retry limit")
def to_clean_float(val, precision=2):
if val is None:
return None
if isinstance(val, Decimal):
return round(float(val), precision)
return round(float(val), precision)
def upsert_metric_snapshot(row):
# row 示例: {"metric_key": "kpi_net_mrr_usd", "curr": Decimal("184250.45"), "prev": Decimal("176100.00"), "as_of": "2026-11-18T06:00:00+08:00"}
query_url = f"https://api.notion.com/v1/databases/{METRIC_DB_ID}/query"
res = notion_request("POST", query_url, {
"filter": {"property": "指标唯一键", "title": {"equals": row["metric_key"]}}
})
props = {
"当前最新值": {"number": to_clean_float(row["curr"], 2)},
"上期对比值": {"number": to_clean_float(row["prev"], 2)},
"最后同步时间": {"date": {"start": row["as_of"]}}
}
if res["results"]:
page_id = res["results"][0]["id"]
notion_request("PATCH", f"https://api.notion.com/v1/pages/{page_id}", {"properties": props})
else:
props["指标唯一键"] = {"title": [{"text": {"content": row["metric_key"]}}]}
notion_request("POST", "https://api.notion.com/v1/pages", {
"parent": {"database_id": METRIC_DB_ID},
"properties": props
})
- 打通模型重命名与废弃血缘审计:当脚本在最新
manifest.json中发现原有dbt_unique_id消失时,不直接删除 Notion 页面,而是将对应模型标记为Deprecated,由关联 Formula 自动触发受影响指标告警。
四、Formula 2.0 数据新鲜度 SLA 与口径异常门禁公式 #
在 DB_Metric_Catalog 中配置如下 Formula 2.0 监控公式(完整函数用法参见 Formula 2.0 实战速查表 与 公式核心指南),可一次性完成“上游模型失败穿透检查 + 数据新鲜度 SLA 超时判定 + 环比剧烈波动异常预警”:
lets(
curr, prop("当前最新值"),
prev, prop("上期对比值"),
slaHours, if(prop("SLA_小时上限") > 0, prop("SLA_小时上限"), 26),
staleHours, if(empty(prop("最后同步时间")), 9999, dateBetween(now(), prop("最后同步时间"), "hours")),
wowPct, if(prev != 0 && !empty(prev), round(((curr - prev) / abs(prev)) * 1000) / 10, 0),
spikeLimit, if(prop("环比波动阈值_Pct") > 0, prop("环比波动阈值_Pct"), 30),
hasFailedModel, prop("关联上游模型").some(current.prop("最近构建状态") == "Fail"),
hasDeprecatedModel, prop("关联上游模型").some(current.prop("最近构建状态") == "Deprecated"),
ifs(
hasFailedModel,
style("🚨 上游 dbt 模型测试失败 · 已熔断指标更新", "red", "bold"),
hasDeprecatedModel,
style("⚠️ 关联模型已废弃或更名 · 请重绑血缘", "orange", "bold"),
staleHours > slaHours,
style("⏰ 数据过期 " + staleHours + "h (SLA " + slaHours + "h)", "red", "bold"),
abs(wowPct) >= spikeLimit,
style("🟠 指标剧烈波动 " + if(wowPct > 0, "+", "") + wowPct + "% · 核查口径或脏数据", "yellow", "bold"),
style("🟢 新鲜健康 (" + staleHours + "h前) · 环比 " + if(wowPct > 0, "+", "") + wowPct + "%", "green")
)
)
五、数仓回写常见故障排查与工程化治理准则 #
下表总结了 Snowflake / BigQuery 与 Notion 集成上线后最常遇到的四类工程故障与处置方案(更多诊断经验详见 Notion 故障排查速查表 与 数据库架构速查表):
| 故障现象 | 根本原因 | 工程化解决策略 |
|---|---|---|
Python 回写报 TypeError: Object of type Decimal is not JSON serializable | BigQuery NUMERIC 与 Snowflake NUMBER 驱动返回高精度 Decimal 类型 | 构造请求体前统一通过 to_clean_float() 转为标准浮点或截断至 4 位小数 |
| dbt 模型重构更名后 Notion 指标卡片失去关联 | 模型文件名从 fct_orders 改为 fct_orders_v2,dbt_unique_id 变化导致原页面变成孤儿数据 | 在 CI 对比前后两版 manifest.json,对消失节点打标 Deprecated 并在 Formula 中高亮提醒重新绑定 |
大批量指标并发回写触发 409 conflict_error | 多个 Airflow Task 同时更新同一个关联模型页面或高频并发写入同一数据库 | 按 指标唯一键 串行队列执行,或将并发数控制在 2~3 req/s 并尊重 Retry-After 响应头 |
| Notion 页面展示数值滞后数仓实际数据 8 小时 | 数仓时间戳为 UTC 零时区,但脚本未附加 +08:00 偏移导致公式 dateBetween 误判 | 从 Snowflake/BigQuery 导出统一转为带偏移的 ISO-8601 字符串(如 2026-11-18T06:00:00+08:00)再写入 Date 属性 |
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。