fabric-integration

Microsoft Fabric 集成

概述

Microsoft Fabric 是一个统一的分析平台，包含 Power BI、Data Factory、Data Engineering、Data Science、Real-Time Intelligence 和 Data Warehouse。Power BI 深度集成其中，作为 Fabric 的可视化和语义建模层。

Direct Lake 模式

Direct Lake 是 Fabric 独有的存储模式，可直接读取 OneLake 中 delta 表的数据，无需导入数据或发送 DirectQuery 请求。

Direct Lake 的工作原理

1. 框定： 刷新时，Direct Lake 仅从 delta 表复制元数据（Parquet 文件引用）——只需几秒
2. 按需加载： 查询访问模型时，数据会从 Parquet 文件直接加载到 VertiPaq 引擎
3. 不重复存储数据： 与 Import 不同，语义模型中不会存储数据副本
4. 性能近似导入模式： 数据加载到内存后，查询速度可达到 VertiPaq 的水平

Direct Lake、Import 和 DirectQuery 对比

特性	Import	DirectQuery	Direct Lake
数据新鲜度	刷新时的快照	实时	近实时（框定后）
查询性能	最快（全部在内存中）	取决于数据源	近似导入模式（按需加载）
刷新时间	几分钟到几小时	不适用	几秒（仅框定）
刷新成本	高（完整复制数据）	无	很低（仅元数据）
数据大小限制	10GB（Premium），1GB（PBIX）	数据源限制	Fabric 容量限制
DAX 支持	完整	有限	完整
计算列	支持	不支持	支持
数据源要求	任意	任意	仅限 OneLake delta 表
容量要求	任意	任意	Fabric F-SKU

Direct Lake 变体（2025-2026 正式发布）

变体	数据源	多数据源	回退	用例	正式发布状态
Direct Lake on OneLake (DL/OL)	OneLake delta 文件	支持（多个 Fabric 项）	不回退	灵活使用多个湖屋	正式发布
Direct Lake on SQL (DL/SQL)	Fabric SQL 终结点	不支持（单个 Fabric 项）	回退到 DirectQuery	以 SQL 为中心，单一数据源	正式发布

创建 Direct Lake 语义模型

在 Power BI Desktop 中（2025+ 预览版）：

1. 获取数据 > OneLake 数据中心
2. 选择 Fabric 湖屋或仓库
3. 选择表（自动以 Direct Lake 模式加载）
4. 在 Desktop 中构建度量值和关系
5. 发布到 Fabric 工作区

通过 Fabric 服务：

1. 在 Fabric 中打开湖屋/仓库
2. 单击“新建语义模型”
3. 选择要包含的表
4. 在 Web 中打开模型以添加度量值和关系

通过 TOM 以编程方式创建：

var database = new Database() { Name = "DirectLakeModel" };
var model = new Model() { Name = "DirectLakeModel" };
database.Model = model;

// Direct Lake partition source
var table = new Table() { Name = "Sales" };
table.Partitions.Add(new Partition() {
    Name = "Sales-DL",
    Mode = ModeType.DirectLake,
    Source = new EntityPartitionSource() {
        EntityName = "Sales",
        SchemaName = "dbo",
        ExpressionSource = new ExpressionSource() {
            Expression = "DatabaseQuery"
        }
    }
});
model.Tables.Add(table);

关键区别： DL/OL 不会回退到 DirectQuery。如果无法从内存提供数据，查询就会失败。这意味着必须在容量护栏范围内谨慎调整 DL/OL 模型的大小。

按容量划分的 Direct Lake 护栏

护栏	F2	F4	F8	F16	F32	F64	F128
磁盘上的模型最大大小	2 GB	4 GB	8 GB	16 GB	32 GB	64 GB	128 GB
每个表的最大行数	300M	300M	300M	1.5B	3B	6B	6B
每个表的最大文件数/行组数	1K	1K	1K	1K	1K	5K	5K
并发 DL 查询数	4	8	16	32	64	128	256

最大内存是用于分页的软限制——超出后会导致性能下降，但不会失败。

磁盘/OneLake 上的模型最大大小是硬性护栏——超出后会回退到 DQ（DL/SQL），或导致查询失败（DL/OL）。

Direct Lake 回退配置

回退行为	设置	影响
自动回退到 DirectQuery	默认（仅 DL/SQL）	查询仍可正常运行，但速度较慢
阻止回退	DirectLakeBehavior = DirectLakeOnly	如果无法从 DL 提供数据，查询会失败
无回退选项	默认（DL/OL）	数据不可用时，查询始终会失败

在 Fabric Capacity Metrics 应用中监控回退——频繁回退表明模型设计存在问题。

常见回退触发因素（DL/SQL）：

• 由于容量限制，列未加载到内存
• Direct Lake 表上的计算列（可能触发 DQ 回退）
• 某些需要完整扫描表的 DAX 模式
• 框架过期（delta 表已更改，但模型未重新框架化）
• 文件数/行组数超过容量防护阈值

使用 Direct Lake 的 Power BI Embedded（2025 年 3 月 GA）

Direct Lake 模式现已全面支持嵌入式分析，并由 Microsoft SLA 提供保障。使用与 Import/DirectQuery 模型相同的嵌入令牌 API，为 Direct Lake 语义模型生成嵌入令牌。

框架化（刷新）

# Trigger framing via REST API
POST https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/datasets/{datasetId}/refreshes
{
  "type": "Automatic"
}

与 Import 刷新（分钟/小时）相比，框架化速度极快（几秒）。安排频繁的框架化，以实现近实时数据。

OneLake

OneLake 是 Fabric 的统一数据湖——一个用于所有分析数据的存储，基于 Azure Data Lake Storage Gen2 构建，采用 delta 格式。

OneLake 快捷方式

无需复制即可连接到外部数据：

快捷方式类型	来源	用例
OneLake	另一个 Fabric 项目	跨工作区共享数据
ADLS Gen2	Azure Data Lake	现有 Azure 数据
S3	Amazon S3	多云数据
GCS	Google Cloud Storage	多云数据
Dataverse	Dynamics 365	业务应用数据

OneLake 文件 API

以编程方式访问 OneLake 数据：

# Using Azure Storage SDK (OneLake supports ADLS Gen2 API)
from azure.storage.filedatalake import DataLakeServiceClient

service_client = DataLakeServiceClient(
    account_url="https://onelake.dfs.fabric.microsoft.com",
    credential=token_credential
)

file_system_client = service_client.get_file_system_client(workspace_id)
directory_client = file_system_client.get_directory_client(f"{lakehouse_name}.Lakehouse/Tables")

Fabric Lakehouse

Lakehouse 将数据湖的灵活性与仓库的 SQL 功能相结合：

Power BI 连接方式：

• **SQL Analytics Endpoint：**用于 DirectQuery 或 Direct Lake 的只读 SQL 端点
• **Delta 表：**Direct Lake 的原生格式
• **笔记本：**通过 Spark 笔记本写入数据，并在 Power BI 中读取

Lakehouse 到 Power BI 的流程

[Data Sources] --> [Fabric Notebooks/Pipelines] --> [Lakehouse Delta Tables]
     |                                                       |
     v                                                       v
[Power Query Dataflows Gen2]                    [Direct Lake Semantic Model]
                                                             |
                                                             v
                                                     [Power BI Reports]

Fabric Warehouse

Fabric 中的全托管 SQL 仓库：

• **T-SQL 支持：**完整的 DML（INSERT、UPDATE、DELETE、MERGE）
• **自动分布式存储：**无需调整索引
• **兼容 Direct Lake：**可将表用作 Direct Lake 数据源
• **跨数据库查询：**跨仓库和 Lakehouse 查询

Dataflow Gen2

基于云的 Fabric ETL，是 Power BI Dataflows 的演进版本：

功能	Dataflow Gen1	Dataflow Gen2
目标位置	仅 Power BI 数据集	Lakehouse、Warehouse、KQL DB、Azure SQL、ADLS Gen2、SharePoint
计算	Power Query Online	Power Query Online + Fabric Spark
暂存	可选（Premium）	始终启用
增量刷新	有限支持	全面支持（2025 年 GA 支持 Lakehouse）
监控	基本	Fabric 监控中心
CI/CD	不支持	Git 集成 + 部署管道（2025 年）
变量库	不支持	参数化源路径和表达式（2025 年）
发布性能	单线程验证	并行化查询验证（2026 年）

**Gen1 弃用：**Microsoft 已宣布 Gen1 属于旧版功能。所有新的开发项目都应迁移到 Gen2。Gen2 支持 Gen1 的所有连接器，以及 Fabric 原生目标位置。

Dataflow Gen2 输出目标位置（2025–2026）

目标位置	协议
Fabric Lakehouse delta 表	Delta/Parquet
Fabric Warehouse 表	T-SQL
Fabric KQL Database 表	KQL
Fabric SQL Database 表	T-SQL
Azure SQL Database 表	T-SQL
Azure Data Explorer (Kusto) 表	KQL
ADLS Gen2 文件	文件（CSV、Parquet）
SharePoint 文件	文件

Dataflow Gen2 到 Direct Lake 管道

1. 在 Fabric 工作区中创建 Dataflow Gen2
2. 连接到数据源（任意 Power Query 连接器）
3. 将目标设置为 Lakehouse（创建 delta 表）
4. 在 lakehouse 表上创建语义模型（Direct Lake）
5. 基于语义模型构建报表

实时智能

Fabric 实时智能项目现已支持 GA 生命周期管理（2025 年）：

项目	ALM 支持	集成
Eventstream	Git + 部署管道	从 Event Hubs、Kafka、IoT Hub、自定义 API 引入数据
Eventhouse	Git + 部署管道	托管 KQL 数据库
KQL Database	Git + 部署管道	从 Power BI 使用 DirectQuery
Real-time Dashboard	Git + 部署管道	用于流式数据的 Fabric 原生仪表板
Data Activator	Git + 部署管道	根据数据条件发出警报/触发操作

Eventstream 到 Power BI 管道

[Event Hubs/Kafka/IoT Hub] --> [Eventstream] --> [KQL Database] --> [Power BI DirectQuery]
                                     |
                                     +--> [Lakehouse] --> [Power BI Direct Lake]

用于数据准备的笔记本

Fabric 笔记本（PySpark/Spark SQL）写入供 Power BI 使用的数据：

# Write DataFrame to lakehouse delta table
df.write.format("delta").mode("overwrite").saveAsTable("Sales")

# Optimized write with partitioning
df.write.format("delta") \
    .partitionBy("Year", "Month") \
    .mode("overwrite") \
    .option("overwriteSchema", "true") \
    .saveAsTable("Sales")

# V-Order optimization (improves Direct Lake read performance)
spark.conf.set("spark.sql.parquet.vorder.enabled", "true")
df.write.format("delta").mode("overwrite").saveAsTable("Sales")

V-Order： 一种写入时优化，可对 Parquet 数据排序，以加快 Direct Lake 读取速度。在笔记本或管道配置中启用。

Power BI 环境中的 Fabric 项目

Fabric 项目	Power BI 集成
Lakehouse	Direct Lake、用于 DQ 的 SQL 终结点
Warehouse	Direct Lake、T-SQL 查询
KQL Database	通过 KQL 连接器使用 DirectQuery
Notebooks	数据准备、通过 sempy 管理模型
Data Pipelines	协调刷新和数据移动
Dataflow Gen2	将数据 ETL 到 lakehouse，供 DL 使用
Eventstream	实时数据流向 KQL，再流向 PBI
ML Models	在笔记本中评分，将结果写入 lakehouse

Semantic Link（sempy）

用于在 Fabric 笔记本中与 Power BI 语义模型交互的 Python 库：

import sempy.fabric as fabric

# List datasets in workspace
datasets = fabric.list_datasets()

# Read data from semantic model using DAX
df = fabric.evaluate_dax(
    dataset="SalesModel",
    dax_string="EVALUATE SUMMARIZECOLUMNS('Date'[Year], 'Product'[Category], \"Sales\", [Total Sales])"
)

# Read model metadata
tables = fabric.list_tables(dataset="SalesModel")
measures = fabric.list_measures(dataset="SalesModel")

# Refresh dataset
fabric.refresh_dataset(dataset="SalesModel")

使用 Direct Lake 的复合模型（2025 预览版）

在单个语义模型中混合使用 Direct Lake 表和 Import 表：

源表	存储模式	适用场景
Lakehouse 事实表	Direct Lake	大型事务数据
Lakehouse 维度	Direct Lake	来自 gold 层的共享维度
外部参考数据	Import	Fabric 中没有的小型表
预算/预测	Import	来自 Excel 或外部数据源的数据

关键注意事项： 同时涉及 DL 和 Import 表的复合模型查询可能具有不同的性能特征。请使用生产数据量进行测试。

其他资源

参考文件

• references/fabric-architecture-patterns.md —— Medallion 架构、数据网格模式和 Fabric 工作区设计策略