e2e-medallion-architecture

遥测 — 必须遵守。 每次 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: e2e-medallion-architecture（az rest：--headers "x-ms-fabric-skill=e2e-medallion-architecture"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项 — 仍需添加。

重要提示

1. 若要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 若要根据工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：列出该工作区中此类型的所有项，然后使用 JMESPath 进行筛选

端到端 Medallion 架构

前置知识

请阅读以下配套文档 — 其中包含此技能所依赖的基础知识：

• COMMON-CORE.md — Fabric REST API 模式、身份验证、令牌受众、项发现
• COMMON-CLI.md — az rest、az login、令牌获取、通过 CLI 使用 Fabric REST
• SPARK-AUTHORING-CORE.md — 笔记本部署、湖仓创建、作业执行
• notebook-api-operations.md — 创建笔记本时必读 — .ipynb 结构要求、单元格格式、getDefinition/updateDefinition 工作流

有关 Spark 特定的优化详情，请参阅 data-engineering-patterns.md。

---

架构概览

Medallion 架构是一种数据湖仓模式，包含三个逐步递进的层：

层	用途	优化配置	使用场景
Bronze（原始层）	按接收时的原样落地原始数据	针对写入优化、仅追加、按摄取日期分区	审计追踪、重新处理、数据沿袭
Silver（清理层）	去重、验证并统一格式的数据	读写均衡、按业务日期分区	特征工程、运营报告
Gold（聚合层）	用于分析的预计算指标	针对读取优化（ZORDER、压缩整理）、按月/年分区	Power BI 报告、仪表板、通过 SQL 端点进行临时分析

• Bronze：读取时定义架构 — 架构灵活；Delta 时间旅行支持审计和回滚
• Silver：架构强制 — 拒绝不符合规范的写入；源发生变化时，使用 mergeSchema 处理架构演变
• Gold：严格的架构治理 — 仅包含经过整理并获业务批准的数据集

---

必须/优先/避免

必须执行

• 根据是否支持架构选择湖仓架构（请参阅 infrastructure-orchestration.md）：
  • 首选： 支持架构的湖仓 → 创建 1 个工作区 + 1 个湖仓，并包含 bronze、silver、gold 架构
  • 旧版： 不支持架构的湖仓 → 为每一层（Bronze、Silver、Gold）创建单独的工作区，以实现治理和访问控制
• 使用 Livy API 创建架构和表——要在支持架构的湖仓中创建架构和表，请通过 Livy 会话提交 Spark SQL 语句（POST /livyApi/versions/2023-12-01/sessions → POST .../statements）。这是在 Fabric 湖仓中执行 DDL 操作（CREATE SCHEMA、CREATE TABLE）的唯一编程式 REST 路径。
• 在 Bronze 中添加元数据列：摄取时间戳、源文件、批次 ID
• 在 Bronze 到 Silver 的转换中应用数据质量规则（去重、空值处理、范围验证）
• 所有奖牌架构层的表都使用 Delta Lake 格式
• 在 Silver/Gold 写入中使用分区感知覆盖，避免重新处理未更改的数据
• 每一层之后都包含验证步骤（行数、架构检查、异常检测）
• 通过 REST API 创建笔记本时，遵循 notebook-api-operations.md 中的 .ipynb 验证与 Fabric 注意事项——每个代码单元格都必须包含 "outputs": [] 和 "execution_count": null
• 完成完整的端到端流程——不要在创建笔记本后就停止；始终绑定湖仓、按顺序执行笔记本（Bronze → Silver → Gold）、验证结果，并将 Power BI 连接到 Gold 层，除非用户明确要求仅进行部分设置
• 在每条关于 MLV 与笔记本的建议中，都要说明 MLV 需要支持架构的湖仓。将 MLV 定义和增量刷新审查交由 spark-cli 的 authoring 模式处理；将计划安排、刷新、监控和故障诊断交由 spark-cli 的 mlv 模式处理。
• 对于定期 MLV 刷新，提供准确的交互路径 Lakehouse → Materialized Lake views → Manage → Schedules。自动化时，使用 POST /workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/refreshMaterializedLakeViews/schedules；绝不要臆造 /mlvRefreshSchedules，也不要通过笔记本计划安排定期刷新。

优先考虑

• 相较于完全刷新，优先采用增量处理（水位线模式）
• 每一层使用独立的笔记本，以便单独测试和调试
• 在 Gold 表中对经常筛选的列使用 ZORDER
• 在 Silver 和 Gold 层写入后运行 OPTIMIZE
• 针对不同环境配置 Spark（Bronze 使用写入密集型配置，Silver 使用均衡型配置，Gold 使用读取密集型配置）
• 使用 OneLake 快捷方式向使用方工作区公开 Gold 数据，避免重复存储
• 明确各层的所有权：工程师负责 Bronze/Silver，分析师负责 Gold
• 使用 Fabric 变量库集中管理各层的路径和配置
• 对治理要求中等或较高的场景，采用多工作区部署模式（Bronze/Silver/Gold 位于不同工作区）
• 当转换可用 Spark SQL 表达且能受益于声明式刷新语义时，对 Silver/Gold 表使用物化湖视图（MLV）。请参阅 spark-cli — Materialized Lake View patterns 和 MLV incremental refresh patterns。
• 将“materialized view”、“spark materialized view”和“MLV”视为同一 Fabric 功能。

避免

• 在单个湖仓中存储所有层，且不使用架构——非架构湖仓需要通过笔记本初始化单元或环境配置来启用 OneLake Spark Catalog，以支持 RLS/CLS 和 MLV。如果没有架构，请使用多个湖仓进行隔离。
• 在有架构的湖仓可用时创建 3 个独立湖仓——改为在一个湖仓内使用架构（更简洁，无需样板初始化单元，也能更高效地进行 MLV 跨架构转换）
• 跳过 Silver 层，直接从 Bronze 进入 Gold
• 硬编码工作区 ID、湖仓 ID 或 FQDN——通过 REST API 发现
• 在 Bronze 表上使用不带 LIMIT 的 SELECT *（这些表会无限增长）
• 未检查下游依赖项就运行 VACUUM
• 在奖章架构各层之间（Bronze→Silver→Gold）串联 OneLake 快捷方式——每一层都必须进行物理实体化，以确保数据血缘和治理
• 将完整实现代码复制到技能中——应引导 LLM 生成代码
• 直接在 Spark 中读取外部 HTTP/HTTPS URL——Fabric Spark 无法访问任意外部 URL；应先将数据载入湖仓 Files/（通过 curl、OneLake API 或 Fabric pipeline Copy activity），然后再从湖仓路径读取
• 通过 REST API 创建笔记本而不验证 .ipynb 结构——代码单元格缺少 execution_count: null 或 outputs: [] 会导致静默失败，或出现“Job instance failed without detail error”错误

---

工作区设置指南

设置奖章架构工作区时，请先选择架构模式（详细指南请参阅 infrastructure-orchestration.md）：

选项 A：启用架构的湖仓（首选）

1. 创建单个工作区：{project}-{env}
2. 创建一个带架构的湖仓：{project}_lakehouse
3. 在湖仓内创建架构：
   • bronze 架构，用于原始数据摄取
   • silver 架构，用于清理和验证后的数据
   • gold 架构，用于聚合分析
4. 选择转换方法：
   • **选项 4a：**为每一层使用笔记本（PySpark 或 Spark SQL 转换）
   • **选项 4b：**使用 Materialized Lake Views（Spark SQL）执行声明式转换并进行增量刷新（查询符合 IR 条件时）——请参阅 materialized-lake-view-patterns.md 和 mlv-incremental-refresh-patterns.md
   • **注意：**PySpark MLV 仅支持完全刷新（不支持增量刷新）——需要 UDF/复杂 Python 逻辑时使用
   • MLV 优势：启用架构的湖仓会自动启用 OneLake Spark Catalog——MLV 开箱即用，无需笔记本初始化单元或环境配置
5. RBAC（可选）：在架构内使用行级安全和列屏蔽进行精细访问控制（同样需要 OneLake Spark Catalog）

选项 B：分离式 Lakehouse（旧版）

1. 创建三个工作区：
   • {project}-bronze-{env}
   • {project}-silver-{env}
   • {project}-gold-{env}
2. 每个工作区创建一个 lakehouse：
   • Bronze 工作区 → {project}_bronze lakehouse
   • Silver 工作区 → {project}_silver lakehouse
   • Gold 工作区 → {project}_gold lakehouse
3. 为各层工作区分配 RBAC：
   • Bronze：摄取/工程写入权限
   • Silver：工程/数据质量权限
   • Gold：分析/BI 使用者访问权限，并采用更严格的整理控制
4. 为非 schema lakehouse 启用 OneLake Spark Catalog（RLS/CLS 和基于目录的访问模式所必需）：
   • **首选：**在 Environment 中设置 spark.sql.fabric.catalog.enable-schemaless-lakehouses=true，并将其附加到笔记本。
   • **替代方案：**从笔记本中省略默认 lakehouse 绑定。使用四段式完全限定引用（workspace.lakehouse.schema.table）。未设置默认 lakehouse 时，OneLake Spark Catalog 会自动启用。
   • 替代方案（内部/不受支持）：在每个笔记本的第一个单元格中添加以下内容：

   %%pyspark
   !echo "spark.sql.fabric.catalog.enable-schemaless-lakehouses=true" >> /home/trusted-service-user/.trident-context
   

   • **⚠️ 注意：**此变通方法使用内部运行时配置路径，该路径可能会在未来的 Fabric 版本中发生变化。为获得稳定且有文档说明的 OneLake Spark Catalog 支持，优先使用启用了 schema 的 lakehouse。
   • 使用此配置时，非 schema lakehouse 支持：
     • ✅ 行级安全性（RLS）和列级安全性（CLS）
   • **注意：**MLV 需要启用了 schema 的 lakehouse（选项 A）。对于非 schema lakehouse，请使用包含 Delta 表的笔记本。

通用步骤（两种选项均适用）

完成上述选项 A 或选项 B 后，执行以下步骤：

1. 为每一层创建笔记本（每个转换阶段一个）——遵循 .ipynb 验证和 Fabric 注意事项
2. 将每个笔记本绑定到其 lakehouse——使用正确的 lakehouse ID 设置 metadata.dependencies.lakehouse（参见 notebook-api-operations.md § 默认 Lakehouse 绑定）：
   • 选项 A：所有笔记本 → 同一 lakehouse，使用 schema 前缀（bronze.table、silver.table）
   • 选项 B：
     • Bronze 笔记本 → Bronze 工作区/lakehouse
     • Silver 笔记本 → Silver 工作区/lakehouse（通过跨工作区 OneLake 访问/完全限定引用读取 Bronze）
     • Gold 笔记本 → Gold 工作区/lakehouse（通过跨工作区访问读取 Silver）
3. 确认笔记本部署——检查 updateDefinition 是否返回 Succeeded；这足以确认内容和 lakehouse 绑定已持久化。不要调用 getDefinition 再次验证——它是异步 LRO，会增加不必要的延迟。
4. 按顺序执行笔记本——先 Bronze，再 Silver，最后 Gold——使用 POST .../jobs/instances?jobType=RunNotebook，并在执行配置中指定正确的 defaultLakehouse（id 和 name 都是必需的）
5. 将 Power BI 连接到 Gold 层——查找 Gold lakehouse SQL 终结点，创建 Direct Lake 语义模型，并在 Gold 汇总表上创建包含可视化效果的报表（参见 Gold 层 → Power BI 使用）
6. 创建管道，用于编排 Bronze → Silver → Gold 流程以供重复执行

明确覆盖：单一工作区

如果用户明确要求部署在单一工作区中（例如，POC/小型团队/单体模式），则保留当前方法：

• 一个工作区包含彼此分离的 Bronze/Silver/Gold lakehouse
• 即使共用工作区，也要在逻辑上保持各层分离
• 说明与多工作区设计相比的治理权衡

按环境参数化：工作区名称后缀（-dev、-prod）、数据量（样例与完整数据）、容量 SKU，以及 Bronze 保留期限。

---

Bronze 层 — 摄取模式

当用户请求将数据摄取到 Bronze 层时，引导 LLM：

1. 先将数据放入湖仓：外部数据必须先暂存到湖仓的 Files/ 文件夹中，Spark 才能读取——可使用以下方式之一：
   • Fabric Pipeline Copy activity（适用于定期加载，优先推荐）——连接外部数据源（HTTP、FTP、数据库、云存储）并将数据写入 OneLake
   • OneLake API / curl——使用 storage.azure.com 令牌通过 REST API 上传文件（参见 COMMON-CLI.md § OneLake Data Access）
   • OneLake Shortcut——适用于已位于 Azure ADLS Gen2、S3 或其他 OneLake 位置的数据
   • notebookutils.fs——在笔记本中从挂载的存储路径复制数据
   • ⚠️ Fabric Spark 无法读取任意 HTTP/HTTPS URL——spark.read.format("csv").load("https://...") 会失败
2. 从湖仓路径读取：数据进入 Files/ 后，使用相对于湖仓的路径读取（例如，spark.read.format("csv").load("Files/landing/daily/")）
3. 添加元数据并写入：添加跟踪列（摄取时间戳、源文件、批次 ID），使用描述性名称创建 Delta 表，按摄取日期分区，并使用追加模式
4. 验证：记录行数，验证架构结构，并标记与历史模式相比的异常

---

Silver 层 — 转换模式

当用户请求将 Bronze 层转换为 Silver 层时，引导 LLM：

• 质量规则：按自然键/复合键去重，筛除无效范围，处理空值（删除必填字段为空的记录，填充可选字段），验证逻辑约束
• 架构一致性：列名使用 snake_case，采用标准化数据类型，创建派生列（持续时间、百分比、类别）
• 架构演进：源架构发生变化时使用 mergeSchema 选项；协调 Gold 表和 Power BI 数据集的下游更新
• 写入策略：按业务日期分区，执行分区感知覆盖，写入后运行 OPTIMIZE，并记录前后指标

---

Gold 层 — 聚合模式

当用户请求 Gold 分析表时，引导 LLM 生成：

• 常见聚合：每日/每周/每月汇总，维度分析（按位置、类别、类型），随时间变化的趋势细分，需求模式（一天中的时段、星期几）
• Spark 会话配置——在 Gold 笔记本中执行任何写入操作之前设置这些属性：

  spark.conf.set("spark.sql.parquet.vorder.default", "true")
  spark.conf.set("spark.databricks.delta.optimizeWrite.enabled", "true")
  spark.conf.set("spark.databricks.delta.optimizeWrite.binSize", "1g")
  

  • V-Order（vorder.default）——对所有 Parquet 文件应用 Fabric 的列式排序优化，显著提升 Direct Lake 和 SQL endpoint 的读取性能
  • Optimize Write（optimizeWrite.enabled）——将小分区合并为大小适宜的文件（每个 binSize 的目标约为 1 GB），减少文件数量并提升扫描效率
• 优化：对筛选列使用 ZORDER，写入后运行 OPTIMIZE，预先聚合指标以避免运行时计算

---

端到端执行流程

设置端到端的奖章架构时，LLM 不得在创建笔记本和部署代码后停止。完整生命周期如下：

Create Resources → Deploy Content → Bind Lakehouses → Execute → Verify Results

分步操作

1. 创建各层的工作区和湖仓（默认） — 每层（Bronze、Silver、Gold）各创建一个工作区和一个湖仓；记录工作区 ID 和湖仓 ID
2. 创建笔记本 — 每层创建一个，并采用有效的 .ipynb 结构（参见 notebook-api-operations.md）
3. 将湖仓绑定到每个笔记本 — 在 .ipynb 载荷中包含 metadata.dependencies.lakehouse，并填入：
   • default_lakehouse：目标湖仓的 GUID
   • default_lakehouse_name：湖仓的显示名称
   • default_lakehouse_workspace_id：工作区的 GUID
4. 部署笔记本内容 — 使用 Base64 编码的 .ipynb 载荷执行 updateDefinition（将内容和湖仓绑定一起部署）
5. 确认部署 — 检查每个 updateDefinition LRO 是否返回 Succeeded；这就足够了。不要调用 getDefinition 进行二次验证——这是一个异步 LRO，会显著增加每个笔记本的延迟。
6. 按顺序执行笔记本 — 使用 POST .../jobs/instances?jobType=RunNotebook：
   • 在 executionData.configuration 中传递同时包含 id 和 name 的 defaultLakehouse
   • 先运行 Bronze → 轮询至 Completed → 再运行 Silver → 轮询 → 最后运行 Gold → 轮询
   • 提交前检查最近的作业（防止重复，参见 SPARK-AUTHORING-CORE.md）
7. 验证结果 — 每个笔记本完成后，确认预期表已创建且行数合理
8. 将 Power BI 连接到 Gold — 在 Gold 汇总表上创建语义模型和报表（参见 Gold Layer → Power BI Consumption）

常见错误：创建笔记本后就停止

如果流程在部署笔记本代码后停止，没有进行绑定或执行：

• 笔记本将没有湖仓上下文 → spark.sql() 和相对路径（Tables/、Files/）在运行时会失败
• 用户看不到任何输出或结果——架构已经搭建，但从未经过测试
• 务必完成到第 7 步，除非用户明确要求在特定步骤停止

---

Gold 层 → Power BI 使用

填充 Gold 表后，将 Power BI 连接起来以展示分析结果。 在 Gold 湖仓之上使用 DirectLake 构建语义模型。

分步操作

1. 发现 Gold 湖仓 SQL 终结点 — 调用 GET /v1/workspaces/{workspaceId}/lakehouses/{goldLakehouseId}，提取 properties.sqlEndpointProperties.connectionString 和 provisioningStatus；等待状态变为 Success
2. 通过 SQL 验证 Gold 表 — 使用 sqlcmd 连接 SQL 终结点（参见 COMMON-CLI.md § SQL / TDS Data-Plane Access），并确认目标表存在：

   SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'nyc_taxi_daily_summary'
   

3. 创建语义模型 — 使用 semantic-model-authoring 技能创建语义模型并部署 TMDL。通过 POST /v1/workspaces/{workspaceId}/items 创建，设置 type: "SemanticModel"，然后使用 TMDL 格式通过 updateDefinition 部署定义（参见 ITEM-DEFINITIONS-CORE.md § SemanticModel）：
   • 模型必须将 Gold 湖仓 SQL 终结点作为其数据源
   • 定义映射到 Gold 汇总表的表（例如，nyc_taxi_daily_summary）
   • 使用 Direct Lake 模式 — 无需导入数据，即可直接连接 OneLake 中的 Delta 表
   • 为你感兴趣的关键聚合指标添加度量值（例如，Total Trips、Avg Fare、Total Revenue、Month over Month Growth）
4. 创建 Power BI 报表 — 使用 POST /v1/workspaces/{workspaceId}/items 创建，设置 type: "Report"，然后使用 PBIR 格式通过 updateDefinition 部署定义（参见 ITEM-DEFINITIONS-CORE.md § Report）：
   • 在 definition.pbir 中引用第 3 步创建的语义模型
   • 至少定义一个包含 Gold 汇总表可视化对象的页面
   • 建议的可视化对象：折线图（日趋势）、卡片（KPI 总计）、柱状图（按类别）、表格（详细视图）
5. 端到端验证 — 使用 semantic-model-authoring 技能进行元数据发现，在语义模型上运行 DAX 查询，并确认数据从 Gold 表流向报表

原则

• 动态发现 SQL 终结点 — 连接字符串位于湖仓响应中的 properties.sqlEndpointProperties.connectionString；切勿将其硬编码
• 等待 SQL 终结点完成预配 — 连接前状态必须为 Success；新建的湖仓可能需要几分钟才能完成预配
• 优先使用 Direct Lake 模式 — 避免数据重复；语义模型直接读取 OneLake 中的 Delta 表
• 表名和列名必须完全匹配 — 语义模型表定义必须使用 Gold 湖仓中的确切 Delta 表名和列名
• 有关语义模型创作（TMDL、刷新、权限），请参阅 semantic-model-authoring 技能
• 有关 DAX 查询验证，请参阅 semantic-model-authoring 技能，了解元数据发现和用于验证的 DAX 查询。

---

管道编排

当用户请求为奖牌式数据流创建管道时，引导 LLM 按以下方式设计：

• 结构：按顺序执行活动（Bronze → Silver → Gold），每个活动都等待前一个活动成功；独立的 Gold 聚合可以并行运行；包含验证和通知活动
• 参数化：管道级处理日期（默认为昨天），传递给所有笔记本；使用动态日期表达式
• 计划安排：每天与源数据刷新时间对齐，基于水位线进行增量处理，并定期执行全量刷新以修正数据
• 错误处理：对暂时性故障进行带退避的重试；对持续性故障发出警报；优雅降级（如果上游失败，下游使用先前的数据）

---

环境优化

有关详细的 Spark 配置和优化策略，请参阅 data-engineering-patterns.md。

层	配置方案	关键设置
Bronze	写入密集型	禁用 V-Order，启用 autoCompact，设置较大的文件目标，按 ingestion_date 分区
Silver	均衡型	启用 V-Order、自适应查询执行，按业务日期分区，在筛选列上使用 ZORDER
Gold	读取密集型	V-Order（spark.sql.parquet.vorder.default=true）、优化写入（optimizeWrite.enabled=true、binSize=1g）、向量化读取器、自适应执行、在所有筛选列上使用 ZORDER、预聚合指标

---

示例

示例 1：设置 Medallion 工作区（默认）

提示词：“为销售分析设置 Medallion 架构，并分别创建 Bronze、Silver 和 Gold 工作区”

LLM 应生成的内容：用于执行以下操作的 REST API 调用：

1. 创建工作区：sales-bronze-dev、sales-silver-dev、sales-gold-dev
2. 在每个工作区中创建一个湖仓：sales_bronze、sales_silver、sales_gold
3. 为每个工作区/层分配 RBAC 角色

# Workspace creation (see COMMON-CLI.md for full patterns)
cat > /tmp/body.json << 'EOF'
{"displayName": "sales-analytics-dev"}
EOF
workspace_id=$(az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --body @/tmp/body.json --query "id" --output tsv)

# Create Bronze lakehouse
cat > /tmp/body.json << 'EOF'
{"displayName": "sales_bronze", "type": "Lakehouse"}
EOF
az rest --method post --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$workspace_id/items" \
  --body @/tmp/body.json

示例 2：设计 Bronze 数据引入

提示词：“将每日 CSV 文件引入 Bronze 湖仓，并添加元数据列”

LLM 应生成的内容：PySpark 笔记本，用于：

1. 使用架构推断或显式架构读取源文件
2. 添加 ingestion_timestamp、source_file、batch_id 列
3. 将数据写入按引入日期分区的 Delta 表
4. 记录行数和验证指标

# Bronze ingestion pattern (guide LLM to generate full implementation)
from pyspark.sql.functions import current_timestamp, input_file_name, lit
import uuid

batch_id = str(uuid.uuid4())
df = (spark.read.format("csv").option("header", True).load("/Files/landing/daily/")
      .withColumn("ingestion_timestamp", current_timestamp())
      .withColumn("source_file", input_file_name())
      .withColumn("batch_id", lit(batch_id)))
df.write.mode("append").partitionBy("ingestion_date").format("delta").saveAsTable("bronze.events_raw")

示例 3：Bronze 到 Silver 的转换

提示词：“清理 Bronze 数据：删除重复项、筛除无效记录、添加派生列，并写入 Silver”

LLM 应生成的内容：应用质量规则和架构一致性检查，并以分区写入方式进行优化的 PySpark 笔记本。

示例 4：端到端管道

提示词：“创建一个管道，每天凌晨 2 点依次运行 Bronze 数据引入、Silver 转换和 Gold 聚合”

LLM 应生成的内容：管道 JSON 定义，包含按顺序执行的笔记本活动、日期参数、重试逻辑和计划触发器。