data-analytics-engineering

数据分析工程

以代码定义数据集市，将指标作为 API，在关键接口上设置契约，仅在有助于提升复用性或供 AI/BI 使用时采用语义层，并通过元数据系统向人类和 Agent 展示所有者、血缘、质量与治理信息。

主要来源：data/sources.json。提供确定性建议前，请依据官方文档核实时效性较强的说法。

适用场景

• 选择或改进分析工程技术栈（dbt、SQLMesh、Coalesce）
• 定义数据集市、粒度、维度、事实表、宽表或活动架构
• 设计或迁移语义层（dbt Semantic Layer、Lightdash、Cube、数仓原生方案）
• 添加数据契约、指标治理、所有权、目录和血缘
• 构建数据质量检查、新鲜度监控、异常检测和发布门禁
• 为仪表板、笔记本、API 或 AI/NLQ 分析准备适用于 BI 的模型

不适用场景

• 湖仓或摄取架构 -> data-lake-platform
• 产品/事件埋点、归因或身份解析 -> marketing-product-analytics
• OLTP 调优、索引、锁或事务数据库操作 -> data-sql-optimization
• Metabase API 自动化 -> data-metabase
• ML 特征工程、实验或模型评估 -> ai-ml-data-science

分诊清单

提出任何建议前，先逐项检查：

• 哪些是权威业务指标？每项指标由谁负责？
• 服务需求是什么：仪表板、笔记本、API、嵌入式分析，还是 AI/NLQ？
• 转换基线是什么：dbt、SQLMesh、可视化工具，还是仅使用数仓 SQL？
• 哪些数据集需要契约（下游使用方依赖其架构、新鲜度或语义）？
• 是否需要语义层，还是当前治理完善的数据集市已足够？
• 现有哪些元数据系统涵盖目录、血缘、所有权、访问权限和质量？

技术栈查询

这些工具的发布阶段、适配器覆盖范围、许可证和企业所有权可能随版本发布和交易而变化。不要凭记忆陈述；应针对其所影响的决策进行查询。本技能中的其他文件会指向此处，而不会重复陈述工具状态。

在推荐……之前	查询内容	主要来源
更换 dbt 引擎（dbt Core 或 Fusion，本地或平台）	用户所用数仓和部署模式对应的发布阶段及适配器可用性	dbt 发布说明以及目标版本的 dbt 升级指南
dbt Semantic Layer / MetricFlow	当前语义 YAML 规范、发布状态和 BI 集成	dbt Semantic Layer 文档；PyPI 上的 MetricFlow 发布历史
SQLMesh	发布状态、许可证和治理机构	SQLMesh 仓库及其基金会项目页面
以供应商风险为由选择某款工具	每个候选工具当前的所有者、许可证和治理机构	供应商新闻页面；各项目的 LICENSE 文件和基金会页面

• **引擎升级：**仅在发布说明列为该部署模式下正式可用的适配器上升级生产环境。对于其他适配器，应在 CI 中让新引擎与当前引擎并行运行，并保持生产环境不变。
• **供应商风险：**分析工具正在整合，因此看似相互独立的两款工具可能由同一所有者持有。不要以“供应商独立性”作为区分依据，除非已核实这一点。如果它们由同一所有者持有，应比较所有权变更后哪些方面仍能保留：你运行的代码所采用的许可证、是否由中立基金会治理该项目，以及模型代码的可移植性如何（纯 SQL，还是供应商专属的模板和配置）。

默认工作流

1. 先锁定指标约定——在 assets/metric-dictionary.md 中定义 KPI 名称、业务逻辑、粒度、负责人和维度
2. 选择一个转换基线——在讨论语义层工具前，统一采用 dbt 或 SQLMesh（references/tool-comparison.md）
3. 为使用场景建模——构建 staging -> intermediate -> marts 分层，并结合 references/modeling-patterns.md 选择最终形态（星型、宽表或活动模式）
4. 为关键接口添加契约——落实对架构、负责人、数据新鲜度和质量预期的要求（references/contracts-catalogs-lineage.md）
5. 仅在确有价值时选择语义服务方案——使用 references/semantic-layer-patterns.md，决定采用 dbt 原生方案、Lightdash、Cube 还是数仓原生方案
6. 添加安全发布的质量控制——静态测试、数据新鲜度检查、审计和异常监控（references/data-quality-testing.md 和 references/release-and-ci-patterns.md）
7. 发布可发现性和治理信息——整理目录资产、血缘、负责人和变更通知（references/metric-governance.md 和 assets/ownership-catalog-worksheet.md）

决策：选择转换基线

What does your team care about most?
  Plan-based deployment, environment isolation, backfill control
    -> SQLMesh
  Broadest ecosystem, contracts, semantic layer, dbt-native CI
    -> dbt (dbt Core or the dbt platform)
  Visual metadata-driven development, enterprise onboarding speed
    -> Coalesce
  Already on dbt and want faster compile + typed SQL
    -> Evaluate dbt Fusion, only on adapters that are GA for your deployment mode (see Stack Lookups)

决策：是否添加语义层？

Are the same business metrics reimplemented in 3+ places?
  NO -> Governed marts only; revisit when the answer flips to YES
  YES ->
    Most consumers are dbt-native?
      YES -> dbt Semantic Layer (MetricFlow) or Lightdash
    Need embedded analytics or product-facing APIs?
      YES -> Cube
    Single warehouse platform?
      Snowflake -> Snowflake Semantic Views
      Databricks -> Unity Catalog Metric Views
    Consumers need a business-friendly metric catalog as much as a query layer?
      YES -> Lightdash (or semantic layer + OpenMetadata/DataHub catalog)

决策：发布前对指标变更进行分类

变更类别	示例	必需的发布流程
增量	新增指标、维度或可选字段	验证粒度和源数据覆盖范围；在对外提供前公布负责人和定义
修正	会改变历史值的错误修复	在有代表性的时间窗口内对旧逻辑和新逻辑进行双跑；量化受影响的时间段和使用方；发布变更通知
破坏性	重命名、移除、更改粒度或重新定义语义	为指标或字段添加版本；保留兼容期；迁移已明确列出的使用方；制定回滚方案

对于修正性和破坏性变更，对账必须在预期粒度上比较总计以及分段结果。总计一致也可能掩盖相互抵消的错误、扇出问题或群体变化。在负责人接受已量化的差异、下游使用方已列明且旧定义在约定窗口内仍可恢复之前，不要切换。

快速参考

任务	资源	何时加载
选择 dbt、SQLMesh 还是 Coalesce	references/tool-comparison.md	选择新技术栈或迁移时
选择星型、宽表还是活动模式	references/modeling-patterns.md	设计数据集市和语义边界时
决定是否添加语义层	references/semantic-layer-patterns.md	复用指标、NLQ、API 或 BI 服务时
添加契约、所有权、血缘和目录	references/contracts-catalogs-lineage.md	共享数据集市和受治理数据集时
添加测试、审计、异常检查和 CI 门禁	references/data-quality-testing.md	防止回归和数据过时
定义指标生命周期和弃用流程	references/metric-governance.md	高管指标和共享 KPI 项目
规划发布、双重运行和回填	references/release-and-ci-patterns.md	安全部署和迁移
PII 隔离、保险库模式、假名化	references/pii-vault-and-pseudonymisation.md	面向 LLM/AI 的查询接口或涉及 GDPR 的场景
起草指标定义	assets/metric-dictionary.md	新建 KPI 或重构指标
起草语义层设计	assets/semantic-layer-spec.md	服务层设计评审
起草质量覆盖方案	assets/data-quality-test-plan.md	按模型规划测试
开始 SQLMesh 项目或模型	assets/transformation/sqlmesh/template-sqlmesh-project.md、assets/transformation/sqlmesh/template-sqlmesh-model.md	设置 SQLMesh 或定义模型；下文列出了所有 SQLMesh 模板
传达指标变更	assets/metric-change-notice.md	指标发生破坏性或非破坏性更新时
记录负责人和目录字段	assets/ownership-catalog-worksheet.md	设置治理和可发现性时
迁移到语义层	assets/semantic-layer-migration-checklist.md	从临时 SQL 迁移到受治理指标时
处理数据质量事件	assets/data-quality-incident-runbook.md	出现故障、数据过时或契约中断时

CI/CD 质量门禁检查清单

dbt 项目（PR 检查）：

dbt deps
dbt parse
# prod-artifacts/ holds the production manifest.json (or set DBT_ENGINE_STATE)
dbt build --select state:modified+ --defer --state ./prod-artifacts

• 无契约模型故障
• 关键数据源的新鲜度检查通过
• 执行高管 KPI 变更的比较查询
• 所有数据集市模型的架构测试通过
• 部署后异常监控未发现新警报

SQLMesh 项目（PR/预览检查）：

sqlmesh plan --no-prompts dev
sqlmesh test
sqlmesh audit   # SQLMesh has no state: selector; audit specific models with --model <name> (repeatable)

• apply 前已审查计划差异
• 本地单元测试通过（未消耗数据仓库计算资源）
• 变更模型的审计通过
• 部署前已确认仅向前执行或回填范围

运作原则

1. 指标就是 API — 名称稳定、负责人明确、变更有版本管理、弃用窗口清晰；不得悄然改变 KPI 的语义。
2. 一个模型，一种粒度 — 数据集市必须具有明确无歧义的粒度；如需采用不同粒度，应创建单独模型，而不是混用。
3. 在共享接口上定义契约 — 高管数据集市、交接表以及供多个团队使用的模型必须定义契约；不要为每个临时暂存模型都定义契约。
4. 语义层是可选的 — 当多个使用方需要受治理的复用、NLQ/AI 访问或产品级指标 API 时再添加；如果受良好治理的数据集市已足够，则无需添加。
5. 元数据服务于人和 Agent — 高价值资产必须包含描述、负责人、血缘、质量状态和访问边界。

常见反模式

反模式	根本原因	修复方法
在仪表板或笔记本中编写 KPI 逻辑	没有受治理的数据集市	先在数据集市或语义模型中定义
在一个数据集市中混用多个粒度	为了方便仪表板使用	按粒度创建单独的模型
在每个暂存模型上都添加契约	错误地应用治理	仅为共享且事关重大的接口添加契约
数据集市尚未稳定就构建语义层	过早抽象	先稳定数据集市，再定义实体和度量
所有请求都使用同一个 360 度表	缺乏建模规范	一个模型、一种粒度、一个用途
允许 AI/NLQ 访问没有文档说明的数据集市	缺少元数据	要求先提供粒度、负责人和新鲜度契约，再允许 AI 访问

已知陷阱

• 缓慢变化维度混入 KPI 联接，悄无声息地改变历史数据。
• 重构指标时，在没有通知、负责人批准或弃用窗口的情况下改变其语义。
• 身份关联、归因和语义指标并存，却没有明确的优先级规则。
• 误以为语义层可以免除发布规范、数据测试和变更沟通的需要。
• 扇出重复：将事实表与存在隐藏一对多关系的维度表联接（例如，每位客户有多个地址、每笔订单有多个归因触点），会悄无声息地使可加指标成倍增加。每次向数据集市添加联接时，都要检查联接前后的行数，而不只是最后检查。
• 语义层中的非可加指标：比率、去重计数和百分位数无法通过简单求和按维度汇总。如果语义层允许使用者按新维度切分预计算的比率，除非指标定义为在查询时根据其基础组成部分重新计算，否则会产生看似合理但实际错误的数字。
• 未按生效时间关联的 SCD Type 2 联接：将事实表与维度表的当前行联接（而不是与事实事件发生时有效的行联接），会在维度属性每次发生变化时重写历史数据——这是“这个月什么都没发生，数字却变了”的常见原因。
• 不具备幂等性的回填：回填或重新处理作业若采用追加而非替换，或缺少自然去重键，就会造成悄无声息的重复计数；如果结构唯一性测试只针对最新分区运行，可能无法发现此问题。
• 新鲜度 SLA 中的时区／夏令时漂移：按当地挂钟时间定义的新鲜度时限每年会有两次失效，也会在 UTC 午夜边界附近失效；应使用 UTC 定义新鲜度阈值，并将日历日粒度视为建模决策，而非源系统时间戳带来的偶然结果。
• 汇总 KPI 中的辛普森悖论：当细分群体占比发生变化时，组织整体指标的变化方向可能与每个底层细分群体都相反；在针对 KPI 整体趋势发出警报之前，应检查细分层级的趋势是否真的与整体趋势一致。

脚本

脚本	用途
scripts/analytics_linter.py	验证、检查并为指标字典 JSON 文件评定健康分数

# Validate required fields, duplicate names, and undefined data sources
python scripts/analytics_linter.py validate --input data/valid-metric-dictionary.json

# Lint metric quality: missing owners, undocumented dimensions, naming, SLAs
python scripts/analytics_linter.py lint --input data/valid-metric-dictionary.json

# Generate a Markdown metric dictionary health report
python scripts/analytics_linter.py report \
  --input data/sample-metric-dictionary.json \
  --output metric-health-report.md

数据

文件	描述
data/sources.json	此技能的精选参考来源
data/valid-metric-dictionary.json	包含 15 个有效指标的生产级字典，用于冒烟测试和快速入门示例
data/sample-metric-dictionary.json	包含 15 个真实指标且存在有意留出的缺口，用于演示检查功能

导航

文件	加载时机
references/tool-comparison.md	选择或比较 dbt、SQLMesh、Coalesce 或语义层工具时
references/modeling-patterns.md	设计数据集市层、粒度、星型／宽表／活动模式时
references/semantic-layer-patterns.md	决定是否采用语义服务层并进行实现时
references/contracts-catalogs-lineage.md	在共享资产上添加数据契约、目录元数据和血缘信息时
references/data-quality-testing.md	构建测试套件、新鲜度检查和异常监控时
references/metric-governance.md	管理、版本化和弃用共享 KPI 时
references/release-and-ci-patterns.md	CI/CD 流水线、双跑验证、回填、安全切换时
references/pii-vault-and-pseudonymisation.md	为大模型／AI 或受 GDPR 约束的界面，将 PII 与分析事实数据分离时
references/transformation-patterns.md	设计 dbt 或 SQLMesh 转换层时（从 data-lake-platform 移入）
references/lake-data-quality-patterns.md	在数据湖原生表上添加 GX／Soda 质量契约时（从 data-lake-platform 移入）

**不在讨论范围内：**因果推断、网络科学、信息论和约束理论分析。对于 DAG 影响范围，请使用 dbt ls -s model+，或在血缘图上使用 len(nx.descendants(G, node))。对于流水线延迟瓶颈，请使用 foundations-theory-of-constraints。对于分析数据上的因果归因、基于互信息的特征选择或网络分析，请使用 foundations-causal-inference、foundations-information-theory 或 foundations-network-science。

模板

• dbt：项目模板
• SQLMesh 设置和建模：项目、模型、增量、DAG
• SQLMesh 验证和运维：测试、生产环境、安全、分层和访问
• assets/metric-dictionary.md
• assets/semantic-layer-spec.md
• assets/data-quality-test-plan.md
• assets/metric-change-notice.md
• assets/ownership-catalog-worksheet.md
• assets/semantic-layer-migration-checklist.md
• assets/data-quality-incident-runbook.md

相关技能

• data-lake-platform — 数据摄取、表格式、编排、数据网格
• data-sql-optimization — 事务型 SQL 性能和运维调优
• marketing-product-analytics — 事件埋点和获客衡量
• data-metabase — Metabase 自动化和仪表板脚本编写
• ai-ml-data-science — 实验和建模工作流

当前来源政策

• 对于供应商功能、语法、定价、限制和受版本发布影响的建议，优先采用 data/sources.json 中 trust_tier: primary 的条目。
• 对于建议类问题，请依据最新官方文档和近期发布说明重新核实。
• 区分已核实的事实与判断；明确标注战略性观点。
• 如果无法访问网络，请说明该建议尚未完全核实。

经验总结循环

如果以往的决策或问题与当前情况相关，且存在 learnings.consolidated.md，请查阅该文件；只有在需要查看历史记录或它是现有的备用文件时，才使用 learnings.md。否则，两者都跳过。

应用这些内容后，如果你遇到了值得记住的模式、需要避免的错误，或让你感到意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点。不要修改 SKILL.md 本身。