Notion 与 Snowflake / BigQuery / dbt 企业级数仓指标回写与数据血缘(Data Lineage)治理实战:从 Reverse ETL 定时同步、指标口径字典到 Formula 2.0 SLA 新鲜度监控闭环

2026 年 11 月 18 日

一、为什么数据团队要用 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 集成指南):

  1. 在 Snowflake / BigQuery 中建立专供 Reverse ETL 的视图层:创建独立 Schema(如 ANALYTICS_EXPORT.NOTION_KPI_SNAPSHOT),采用静态字段名输出 metric_key、current_value、previous_value 与 as_of_timestamp,避免底层宽表增减列影响导出契约。
  2. 提取 dbt 血缘与构建产物:在 Airflow、GitHub Actions 或 Dagster 任务末尾读取 target/manifest.json 与 target/run_results.json,校验目标 Mart 模型当日的 unique、not_null 测试是否全部通过;若上游测试失败,立即熔断指标回写,并仅更新 DB_Dbt_Models 状态为 Fail。
  3. 显式处理高精度浮点(Decimal / BIGNUMERIC)与时间精度:Snowflake 的 NUMBER(38,6) 与 BigQuery 的 NUMERIC 在 Python 中默认返回 Decimal 对象,JSON 序列化会直接报错;回写 Notion Number 属性前必须显式转换为四舍五入后的 float(如保留 2~4 位小数)。
  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
        })
  1. 打通模型重命名与废弃血缘审计:当脚本在最新 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)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。