使用 dlt 将数据加载到 Microsoft Fabric Warehouse完整配置指南与源码解析【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltdltdata load tool为 Microsoft Fabric Warehouse 提供了开箱即用的目标destination支持。本文以官方文档 fabric.md 为核心骨架结合仓库中dlt/destinations/impl/fabric/的源码实现与测试用例系统讲解从安装、Service Principal 认证、staging 配置、类型映射到故障排查的完整实战流程。读完本文你将能够基于 Service Principal 认证把 dlt 管道稳定地加载到 Fabric Warehouse并理解其底层 COPY INTO、varchar/datetime2 类型转换与 UTF-8 排序规则的设计原理。1. 概览Fabric Warehouse 目标destinationMicrosoft Fabric Warehouse 是微软 OneLake 体系下的数据仓库服务底层技术基于 SQL Server / Synapse。dlt的 Fabric 目标通过在dlt/destinations/impl/fabric/目录下的专属实现factory.py、fabric.py、sql_client.py、configuration.py扩展 Synapse 能力专门适配 Fabric 的差异化特性使用fabricSQLglot 方言生成正确的 SQL用varchar替代nvarcharFabric 不支持 nvarchar用datetime2替代datetimeoffsetFabric 不支持 datetimeoffset支持通过 OneLake / Azure Blob 存储的COPY INTO高效批量加载针对 UTF-8 排序规则自动配置LongAsMaxyes。2. 安装与依赖2.1 安装 dlt 的 Fabric 扩展在官方文档中安装命令如下pip install dlt[fabric]该命令会安装dlt以及mssql扩展extra中与 SQL Server 客户端相关的全部依赖——Fabric Warehouse 通过 SQL Server 兼容的 pyodbc 协议连接。从 configuration.py 可以看到FabricCredentials的drivername默认即为mssqlpyodbc。2.2 系统级前置条件ODBC DriverMicrosoft ODBC Driver for SQL Server无法随dlt的 Python 依赖一同安装必须单独在运行环境安装。官方文档支持以下版本ODBC Driver 18 for SQL Server推荐ODBC Driver 17 for SQL Server你可以通过配置项显式指定驱动名称见 第 10.2 节。例如在 Ubuntu/Debian 上安装# Ubuntu/Debian curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list sudo apt-get update sudo ACCEPT_EULAY apt-get install -y msodbcsql18提示ODBC 驱动的实际校验发生在建立连接阶段而非配置解析阶段。测试用例 test_fabric_configuration.py 明确验证了这一点即使未安装驱动配置也能正常构造成功。3. Service Principal 认证3.1 认证要求Fabric Warehouse必须使用 Azure Active DirectoryAzure ADService Principal 认证不支持用户名/密码方式。你需要准备以下信息Tenant ID你的 Azure AD 租户 IDGUIDClient ID应用程序服务主体客户端 IDGUIDClient Secret应用程序客户端密钥HostFabric Warehouse 的 SQL 端点DatabaseWarehouse 中的数据库名如何找到 SQL 端点在 Fabric 门户中打开你的 Warehouse设置Settings选择SQL endpoint复制SQL 连接字符串其格式为guid.datawarehouse.fabric.microsoft.com3.2 凭据结构源码解析FabricCredentials继承自AzureServicePrincipalCredentials见 configuration.py因此天然具备 Service Principal 字段与自动回退到DefaultAzureCredential的能力。核心字段包括字段默认值说明drivernamemssqlpyodbcSQLAlchemy 驱动名host无Fabric Warehouse 主机如guid.datawarehouse.fabric.microsoft.comport1433数据库端口database无Fabric Warehouse 数据库名connect_timeout15连接超时秒在 on_partial 中实现了一个重要的回退逻辑如果显式的azure_client_id/azure_client_secret/azure_tenant_id三者缺失则会尝试使用DefaultAzureCredential()作为默认凭据只要host与database已提供就会继续解析。这意味着在本地开发环境或已登录 Azure CLI 的环境中即便不填写 Service Principal 密钥也可能完成认证。3.3 生成 ODBC DSNget_odbc_dsn_dict 负责构建连接参数关键项包括AUTHENTICATIONActiveDirectoryServicePrincipal服务主体认证方式LongAsMaxyesUTF-8 排序规则所必需始终开启Encryptyes、TrustServerCertificateno强制加密连接当提供 Service Principal 三元组时UID自动组合为client_idtenant_idPWD为 client secret测试用例 test_fabric_configuration.py 对上述 DSN 参数逐项断言可作为自检清单。4. 创建管道从初始化到首次加载官方文档给出了三步创建管道的流程第 1 步初始化项目dlt init chess fabric该命令生成一个以chess为示例数据源、目标为fabric的管道项目骨架。第 2 步安装依赖pip install -r requirements.txt或直接安装pip install dlt[fabric]第 3 步在.dlt/secrets.toml中填写凭据[destination.fabric.credentials] host your-warehouse-guid.datawarehouse.fabric.microsoft.com database mydb azure_tenant_id your-azure-tenant-id azure_client_id your-client-id azure_client_secret your-client-secret port 1433 connect_timeout 30也可以直接在代码中通过dlt.destinations.fabric(...)构造见 第 9.2 节。5. Write Disposition写入策略Fabric 目标支持全部写入策略包括upsert与insert-only两种 merge 策略。当你在replace策略中使用staging-optimized时目标表会被drop 后通过ALTER SCHEMA ... TRANSFER重新创建。该操作是原子的Fabric 支持 DDL 事务。6. Staging 支持OneLake 与 Azure Blob6.1 为什么需要 stagingFabric 的加载路径分两种源码 fabric.py 中create_load_job的实现可以印证直接加载默认通过 INSERT 语句写入仅支持insert_values格式受限于单条 INSERT 最多 1000 行Staging 加载对于 parquet 等大批量文件Fabric 必须配置 stagingOneLake Lakehouse 或 Azure Blob / Data Lake Storage通过COPY INTO命令批量加载。这也是官方文档推荐的大数据集方案。从源码看非 staging 场景下若遇到 parquet 文件会直接抛出错误并提示Configure staging with filesystem destination——这解释了为什么大表加载一定要配置 staging。6.2 管道中配置 stagingimport dlt pipeline dlt.pipeline( destinationfabric, stagingfilesystem, dataset_namemy_dataset )6.3 使用 OneLake 作为 staging.dlt/secrets.toml[destination.fabric.credentials] # your fabric credentials [destination.filesystem] bucket_url abfss://your-workspace-guidonelake.dfs.fabric.microsoft.com/your-lakehouse-guid/Files [destination.filesystem.credentials] azure_storage_account_name onelake azure_account_host onelake.blob.fabric.microsoft.com # use same Service Principal credentials as in [destination.fabric.credentials] azure_tenant_id your-tenant-id azure_client_id your-client-id azure_client_secret your-client-secret查找 GUID 的方法在浏览器中打开你的 Fabric workspaceworkspace GUID 位于 URL 中https://fabric.microsoft.com/groups/workspace_guid/...打开你的 Lakehouselakehouse GUID 位于 URL 中https://fabric.microsoft.com/.../lakehouses/lakehouse_guid重要bucket_url必须使用 workspace 和 lakehouse 的GUID 而非显示名称configuration.py 的 docstring 明确强调。6.4 使用 Azure Blob / Data Lake Storage 作为 staging.dlt/secrets.toml[destination.fabric.credentials] # your fabric credentials [destination.filesystem] bucket_url az://your-container-name [destination.filesystem.credentials] azure_storage_account_name your-storage-account-name azure_storage_account_key your-storage-account-key6.5 COPY INTO 的底层实现FabricCopyFileLoadJobfabric.py是 COPY INTO 的核心实现根据文件扩展名判断文件类型仅支持PARQUET其他类型直接报错对于 OneLakeabfss://onelake.dfs.fabric.microsoft.com主机路径会将abfss路径转换为https://onelake.dfs.fabric.microsoft.com/workspace/path形式供 COPY INTO 使用对于普通 Azure Storage则使用 SAS token 凭证IDENTITY Shared Access SignatureOneLake Service Principal 场景下会先通过_ensure_fabric_token_initializedfabric.py调用 Fabric API 初始化令牌——这一初始化结果按client_id缓存在类级字典中避免批量加载多个文件时因频繁调用 API 触发限流。7. 数据加载与文件格式7.1 加载方式默认通过INSERT 语句加载数据。Fabric Warehouse 单条 INSERT 有 1000 行上限dlt即按此上限执行。7.2 支持的格式insert-values是默认且当前唯一支持的直接加载格式。从 factory.py 的能力声明看该格式策略继承自 Synapse直接加载使用insert_valuesstaging 使用 parquet。8. 列提示Column Hints与标识符8.1 索引创建默认关闭fabric目标会为带unique提示的列创建唯一索引但该行为默认关闭。源码依据在 fabric.py当create_indexesFalse默认时primary_key与unique提示会从active_hints中被移除。测试 test_fabric_table_builder.py 也验证了默认情况下 SQL 中不会出现PRIMARY KEY与UNIQUE约束。启用方式见 第 10.1 节。8.2 大小写不敏感的标识符Fabric Warehouse与 SQL Server 一致使用大小写不敏感标识符但会保留存储在 INFORMATION SCHEMA 中的标识符大小写。你可以使用大小写敏感命名约定来保持标识符大小写。注意这存在产生标识符冲突的风险dlt会检测到冲突并使加载过程失败。从 factory.py 的adjust_capabilities可以看到当has_case_sensitive_identifiers为 True 时会设置casefold_identifier str即不做大小写折叠以配合大小写敏感的排序规则。9. 类型映射与排序规则Data Types CollationFabric Warehouse 与标准 SQL Server 在类型系统上有几处关键差异全部体现在FabricTypeMapperfactory.py中。9.1 VARCHAR vs NVARCHARFabric Warehouse 使用varchar而非nvarchar存储文本列。由于varchar长度按字节计算而precision按字符计算因此precision需乘以 4UTF-8 单字符最多 4 字节text→varchar(max)带precision的text→varchar(precision * 4)例如precision25→varchar(100)precision超过 2000 的text→varchar(max)因为 8000 是 Fabric 接受的最长显式长度测试用例 test_fabric_type_mapper_scales_varchar_precision 精确验证了这条换算链precision100 → varchar(400)、precision2000 → varchar(8000)、precision2001 → varchar(max)。9.2 DATETIME2 vs DATETIMEOFFSETFabric 使用datetime2存储时间戳而非datetimeoffsettimestamp→datetime2(6)精度限制为 0-6而非 0-7time→time(6)必须显式指定精度从源码看to_db_datetime_type会把超出范围的精度钳制到 0-6默认使用datetime2(6)FabricTypeMapper还会兜底地把任何datetimeoffset替换为datetime2。同时能力声明中max_timestamp_precision 6、supports_tz_aware_datetime Falsefactory.py意味着时区信息在写入时会被丢弃——这是 Fabric 的固有限制。9.3 JSON 存储Fabric 不支持原生 JSON 列JSON 对象统一存储为varchar(max)列。9.4 排序规则CollationFabric Warehouse 支持 UTF-8 排序规则。目标会自动配置LongAsMaxyes这是 UTF-8 排序规则正常工作的前提。默认排序规则Latin1_General_100_BIN2_UTF8区分大小写、UTF-8你可以在配置中指定其他排序规则TOML 方式[destination.fabric] collation Latin1_General_100_CI_AS_KS_WS_SC_UTF8 # case-insensitive或者在代码中指定pipeline dlt.pipeline( destinationdlt.destinations.fabric( credentials{}, collationLatin1_General_100_CI_AS_KS_WS_SC_UTF8 ) )排序规则会影响标识符大小写敏感性默认的BIN2二进制排序规则区分大小写而CIcase-insensitive不区分。配置层的collation默认值与能力层的has_case_sensitive_identifiers相互配合见 configuration.py。10. 其他目标选项10.1 启用唯一索引创建fabric目标默认不会为带unique提示如_dlt_id的列创建唯一索引。要启用该行为[destination.fabric] create_indexestrue启用后建表 SQL 中会生成UNIQUE NOT ENFORCED/PRIMARY KEY NONCLUSTERED NOT ENFORCED约束Fabric 的约束是不强制执行的。测试 test_fabric_table_builder.py 完整覆盖了默认关闭与显式启用两种路径。10.2 显式指定 ODBC 驱动名称[destination.fabric.credentials] driverODBC Driver 18 for SQL Server11. 与 MSSQL 目标的主要差异尽管 Fabric Warehouse 基于 SQL Server两者存在关键差异认证方式Fabric 必须使用 Service Principal不支持用户名/密码认证类型系统使用varchar与datetime2而非nvarchar与datetimeoffset排序规则针对 UTF-8 排序规则优化自动配置LongAsMaxSQL 方言使用fabricSQLglot 方言生成 SQL此外还有一些实现层面的差异值得一提Fabric 不支持表索引存储由系统自动管理因此建表 SQL 中不会出现WITH (HEAP)或WITH (CLUSTERED COLUMNSTORE INDEX)子句fabric.py_get_column_def_sql也绕过了 mssql 对唯一文本列的 900 字节上限fabric.py因为 Fabric 没有索引键限制。11.1 dbt 支持与 dbt 的集成通过dbt-fabric提供支持。Service Principal 与默认 Azure 凭据两种方式都受支持并与 dbt runner 共享。12. 状态同步该目标完整支持 dlt state sync即管道状态incremental 游标、资源状态等可以随数据一同同步到 Fabric Warehouse保证增量加载的连续性。13. 故障排查13.1 ODBC 驱动未找到若出现No supported ODBC driver found请安装 Microsoft ODBC Driver 18 for SQL Server安装命令见 第 2.2 节。13.2 认证失败请确认你的 Service Principal在 Fabric workspace 上具有适当权限有权访问目标数据库 / WarehouseTenant ID 正确应该是你的 Azure AD 租户 ID而非 workspace / capacity ID13.3 UTF-8 字符问题如果遇到字符编码问题确认你的 Warehouse 使用 UTF-8 排序规则检查连接中是否带有LongAsMaxyes该目标会自动添加如有需要可改用不区分大小写的 UTF-8 排序规则14. 相关资源Microsoft Fabric DocumentationFabric Warehouse DocumentationService Principal Setup Guide源码Fabric 目标实现位于 dlt/destinations/impl/fabric/测试用例位于 tests/load/fabric/可深入阅读以验证本文所有结论【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 dlt 将数据加载到 Microsoft Fabric Warehouse：完整配置指南与源码解析
使用 dlt 将数据加载到 Microsoft Fabric Warehouse完整配置指南与源码解析【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltdltdata load tool为 Microsoft Fabric Warehouse 提供了开箱即用的目标destination支持。本文以官方文档 fabric.md 为核心骨架结合仓库中dlt/destinations/impl/fabric/的源码实现与测试用例系统讲解从安装、Service Principal 认证、staging 配置、类型映射到故障排查的完整实战流程。读完本文你将能够基于 Service Principal 认证把 dlt 管道稳定地加载到 Fabric Warehouse并理解其底层 COPY INTO、varchar/datetime2 类型转换与 UTF-8 排序规则的设计原理。1. 概览Fabric Warehouse 目标destinationMicrosoft Fabric Warehouse 是微软 OneLake 体系下的数据仓库服务底层技术基于 SQL Server / Synapse。dlt的 Fabric 目标通过在dlt/destinations/impl/fabric/目录下的专属实现factory.py、fabric.py、sql_client.py、configuration.py扩展 Synapse 能力专门适配 Fabric 的差异化特性使用fabricSQLglot 方言生成正确的 SQL用varchar替代nvarcharFabric 不支持 nvarchar用datetime2替代datetimeoffsetFabric 不支持 datetimeoffset支持通过 OneLake / Azure Blob 存储的COPY INTO高效批量加载针对 UTF-8 排序规则自动配置LongAsMaxyes。2. 安装与依赖2.1 安装 dlt 的 Fabric 扩展在官方文档中安装命令如下pip install dlt[fabric]该命令会安装dlt以及mssql扩展extra中与 SQL Server 客户端相关的全部依赖——Fabric Warehouse 通过 SQL Server 兼容的 pyodbc 协议连接。从 configuration.py 可以看到FabricCredentials的drivername默认即为mssqlpyodbc。2.2 系统级前置条件ODBC DriverMicrosoft ODBC Driver for SQL Server无法随dlt的 Python 依赖一同安装必须单独在运行环境安装。官方文档支持以下版本ODBC Driver 18 for SQL Server推荐ODBC Driver 17 for SQL Server你可以通过配置项显式指定驱动名称见 第 10.2 节。例如在 Ubuntu/Debian 上安装# Ubuntu/Debian curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list sudo apt-get update sudo ACCEPT_EULAY apt-get install -y msodbcsql18提示ODBC 驱动的实际校验发生在建立连接阶段而非配置解析阶段。测试用例 test_fabric_configuration.py 明确验证了这一点即使未安装驱动配置也能正常构造成功。3. Service Principal 认证3.1 认证要求Fabric Warehouse必须使用 Azure Active DirectoryAzure ADService Principal 认证不支持用户名/密码方式。你需要准备以下信息Tenant ID你的 Azure AD 租户 IDGUIDClient ID应用程序服务主体客户端 IDGUIDClient Secret应用程序客户端密钥HostFabric Warehouse 的 SQL 端点DatabaseWarehouse 中的数据库名如何找到 SQL 端点在 Fabric 门户中打开你的 Warehouse设置Settings选择SQL endpoint复制SQL 连接字符串其格式为guid.datawarehouse.fabric.microsoft.com3.2 凭据结构源码解析FabricCredentials继承自AzureServicePrincipalCredentials见 configuration.py因此天然具备 Service Principal 字段与自动回退到DefaultAzureCredential的能力。核心字段包括字段默认值说明drivernamemssqlpyodbcSQLAlchemy 驱动名host无Fabric Warehouse 主机如guid.datawarehouse.fabric.microsoft.comport1433数据库端口database无Fabric Warehouse 数据库名connect_timeout15连接超时秒在 on_partial 中实现了一个重要的回退逻辑如果显式的azure_client_id/azure_client_secret/azure_tenant_id三者缺失则会尝试使用DefaultAzureCredential()作为默认凭据只要host与database已提供就会继续解析。这意味着在本地开发环境或已登录 Azure CLI 的环境中即便不填写 Service Principal 密钥也可能完成认证。3.3 生成 ODBC DSNget_odbc_dsn_dict 负责构建连接参数关键项包括AUTHENTICATIONActiveDirectoryServicePrincipal服务主体认证方式LongAsMaxyesUTF-8 排序规则所必需始终开启Encryptyes、TrustServerCertificateno强制加密连接当提供 Service Principal 三元组时UID自动组合为client_idtenant_idPWD为 client secret测试用例 test_fabric_configuration.py 对上述 DSN 参数逐项断言可作为自检清单。4. 创建管道从初始化到首次加载官方文档给出了三步创建管道的流程第 1 步初始化项目dlt init chess fabric该命令生成一个以chess为示例数据源、目标为fabric的管道项目骨架。第 2 步安装依赖pip install -r requirements.txt或直接安装pip install dlt[fabric]第 3 步在.dlt/secrets.toml中填写凭据[destination.fabric.credentials] host your-warehouse-guid.datawarehouse.fabric.microsoft.com database mydb azure_tenant_id your-azure-tenant-id azure_client_id your-client-id azure_client_secret your-client-secret port 1433 connect_timeout 30也可以直接在代码中通过dlt.destinations.fabric(...)构造见 第 9.2 节。5. Write Disposition写入策略Fabric 目标支持全部写入策略包括upsert与insert-only两种 merge 策略。当你在replace策略中使用staging-optimized时目标表会被drop 后通过ALTER SCHEMA ... TRANSFER重新创建。该操作是原子的Fabric 支持 DDL 事务。6. Staging 支持OneLake 与 Azure Blob6.1 为什么需要 stagingFabric 的加载路径分两种源码 fabric.py 中create_load_job的实现可以印证直接加载默认通过 INSERT 语句写入仅支持insert_values格式受限于单条 INSERT 最多 1000 行Staging 加载对于 parquet 等大批量文件Fabric 必须配置 stagingOneLake Lakehouse 或 Azure Blob / Data Lake Storage通过COPY INTO命令批量加载。这也是官方文档推荐的大数据集方案。从源码看非 staging 场景下若遇到 parquet 文件会直接抛出错误并提示Configure staging with filesystem destination——这解释了为什么大表加载一定要配置 staging。6.2 管道中配置 stagingimport dlt pipeline dlt.pipeline( destinationfabric, stagingfilesystem, dataset_namemy_dataset )6.3 使用 OneLake 作为 staging.dlt/secrets.toml[destination.fabric.credentials] # your fabric credentials [destination.filesystem] bucket_url abfss://your-workspace-guidonelake.dfs.fabric.microsoft.com/your-lakehouse-guid/Files [destination.filesystem.credentials] azure_storage_account_name onelake azure_account_host onelake.blob.fabric.microsoft.com # use same Service Principal credentials as in [destination.fabric.credentials] azure_tenant_id your-tenant-id azure_client_id your-client-id azure_client_secret your-client-secret查找 GUID 的方法在浏览器中打开你的 Fabric workspaceworkspace GUID 位于 URL 中https://fabric.microsoft.com/groups/workspace_guid/...打开你的 Lakehouselakehouse GUID 位于 URL 中https://fabric.microsoft.com/.../lakehouses/lakehouse_guid重要bucket_url必须使用 workspace 和 lakehouse 的GUID 而非显示名称configuration.py 的 docstring 明确强调。6.4 使用 Azure Blob / Data Lake Storage 作为 staging.dlt/secrets.toml[destination.fabric.credentials] # your fabric credentials [destination.filesystem] bucket_url az://your-container-name [destination.filesystem.credentials] azure_storage_account_name your-storage-account-name azure_storage_account_key your-storage-account-key6.5 COPY INTO 的底层实现FabricCopyFileLoadJobfabric.py是 COPY INTO 的核心实现根据文件扩展名判断文件类型仅支持PARQUET其他类型直接报错对于 OneLakeabfss://onelake.dfs.fabric.microsoft.com主机路径会将abfss路径转换为https://onelake.dfs.fabric.microsoft.com/workspace/path形式供 COPY INTO 使用对于普通 Azure Storage则使用 SAS token 凭证IDENTITY Shared Access SignatureOneLake Service Principal 场景下会先通过_ensure_fabric_token_initializedfabric.py调用 Fabric API 初始化令牌——这一初始化结果按client_id缓存在类级字典中避免批量加载多个文件时因频繁调用 API 触发限流。7. 数据加载与文件格式7.1 加载方式默认通过INSERT 语句加载数据。Fabric Warehouse 单条 INSERT 有 1000 行上限dlt即按此上限执行。7.2 支持的格式insert-values是默认且当前唯一支持的直接加载格式。从 factory.py 的能力声明看该格式策略继承自 Synapse直接加载使用insert_valuesstaging 使用 parquet。8. 列提示Column Hints与标识符8.1 索引创建默认关闭fabric目标会为带unique提示的列创建唯一索引但该行为默认关闭。源码依据在 fabric.py当create_indexesFalse默认时primary_key与unique提示会从active_hints中被移除。测试 test_fabric_table_builder.py 也验证了默认情况下 SQL 中不会出现PRIMARY KEY与UNIQUE约束。启用方式见 第 10.1 节。8.2 大小写不敏感的标识符Fabric Warehouse与 SQL Server 一致使用大小写不敏感标识符但会保留存储在 INFORMATION SCHEMA 中的标识符大小写。你可以使用大小写敏感命名约定来保持标识符大小写。注意这存在产生标识符冲突的风险dlt会检测到冲突并使加载过程失败。从 factory.py 的adjust_capabilities可以看到当has_case_sensitive_identifiers为 True 时会设置casefold_identifier str即不做大小写折叠以配合大小写敏感的排序规则。9. 类型映射与排序规则Data Types CollationFabric Warehouse 与标准 SQL Server 在类型系统上有几处关键差异全部体现在FabricTypeMapperfactory.py中。9.1 VARCHAR vs NVARCHARFabric Warehouse 使用varchar而非nvarchar存储文本列。由于varchar长度按字节计算而precision按字符计算因此precision需乘以 4UTF-8 单字符最多 4 字节text→varchar(max)带precision的text→varchar(precision * 4)例如precision25→varchar(100)precision超过 2000 的text→varchar(max)因为 8000 是 Fabric 接受的最长显式长度测试用例 test_fabric_type_mapper_scales_varchar_precision 精确验证了这条换算链precision100 → varchar(400)、precision2000 → varchar(8000)、precision2001 → varchar(max)。9.2 DATETIME2 vs DATETIMEOFFSETFabric 使用datetime2存储时间戳而非datetimeoffsettimestamp→datetime2(6)精度限制为 0-6而非 0-7time→time(6)必须显式指定精度从源码看to_db_datetime_type会把超出范围的精度钳制到 0-6默认使用datetime2(6)FabricTypeMapper还会兜底地把任何datetimeoffset替换为datetime2。同时能力声明中max_timestamp_precision 6、supports_tz_aware_datetime Falsefactory.py意味着时区信息在写入时会被丢弃——这是 Fabric 的固有限制。9.3 JSON 存储Fabric 不支持原生 JSON 列JSON 对象统一存储为varchar(max)列。9.4 排序规则CollationFabric Warehouse 支持 UTF-8 排序规则。目标会自动配置LongAsMaxyes这是 UTF-8 排序规则正常工作的前提。默认排序规则Latin1_General_100_BIN2_UTF8区分大小写、UTF-8你可以在配置中指定其他排序规则TOML 方式[destination.fabric] collation Latin1_General_100_CI_AS_KS_WS_SC_UTF8 # case-insensitive或者在代码中指定pipeline dlt.pipeline( destinationdlt.destinations.fabric( credentials{}, collationLatin1_General_100_CI_AS_KS_WS_SC_UTF8 ) )排序规则会影响标识符大小写敏感性默认的BIN2二进制排序规则区分大小写而CIcase-insensitive不区分。配置层的collation默认值与能力层的has_case_sensitive_identifiers相互配合见 configuration.py。10. 其他目标选项10.1 启用唯一索引创建fabric目标默认不会为带unique提示如_dlt_id的列创建唯一索引。要启用该行为[destination.fabric] create_indexestrue启用后建表 SQL 中会生成UNIQUE NOT ENFORCED/PRIMARY KEY NONCLUSTERED NOT ENFORCED约束Fabric 的约束是不强制执行的。测试 test_fabric_table_builder.py 完整覆盖了默认关闭与显式启用两种路径。10.2 显式指定 ODBC 驱动名称[destination.fabric.credentials] driverODBC Driver 18 for SQL Server11. 与 MSSQL 目标的主要差异尽管 Fabric Warehouse 基于 SQL Server两者存在关键差异认证方式Fabric 必须使用 Service Principal不支持用户名/密码认证类型系统使用varchar与datetime2而非nvarchar与datetimeoffset排序规则针对 UTF-8 排序规则优化自动配置LongAsMaxSQL 方言使用fabricSQLglot 方言生成 SQL此外还有一些实现层面的差异值得一提Fabric 不支持表索引存储由系统自动管理因此建表 SQL 中不会出现WITH (HEAP)或WITH (CLUSTERED COLUMNSTORE INDEX)子句fabric.py_get_column_def_sql也绕过了 mssql 对唯一文本列的 900 字节上限fabric.py因为 Fabric 没有索引键限制。11.1 dbt 支持与 dbt 的集成通过dbt-fabric提供支持。Service Principal 与默认 Azure 凭据两种方式都受支持并与 dbt runner 共享。12. 状态同步该目标完整支持 dlt state sync即管道状态incremental 游标、资源状态等可以随数据一同同步到 Fabric Warehouse保证增量加载的连续性。13. 故障排查13.1 ODBC 驱动未找到若出现No supported ODBC driver found请安装 Microsoft ODBC Driver 18 for SQL Server安装命令见 第 2.2 节。13.2 认证失败请确认你的 Service Principal在 Fabric workspace 上具有适当权限有权访问目标数据库 / WarehouseTenant ID 正确应该是你的 Azure AD 租户 ID而非 workspace / capacity ID13.3 UTF-8 字符问题如果遇到字符编码问题确认你的 Warehouse 使用 UTF-8 排序规则检查连接中是否带有LongAsMaxyes该目标会自动添加如有需要可改用不区分大小写的 UTF-8 排序规则14. 相关资源Microsoft Fabric DocumentationFabric Warehouse DocumentationService Principal Setup Guide源码Fabric 目标实现位于 dlt/destinations/impl/fabric/测试用例位于 tests/load/fabric/可深入阅读以验证本文所有结论【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考