databricks-lakeflow-connect

Lakeflow Connect

构建托管式摄取管道，将 SaaS 应用和数据库中的数据拉取到 Unity Catalog Delta 表中，全程受治理，并由无服务器 Lakeflow Spark Declarative Pipelines（原名 Delta Live Tables / DLT）提供支持。

状态： 混合目录——包含可用于生产环境的 GA 连接器，以及随时间不断扩展的 Public Preview、Beta 和 Private Preview 连接器。请参阅下方的连接器目录。

---

什么是 Lakeflow Connect？

用于从 SaaS 应用和数据库摄取数据的托管连接器。生成的摄取管道由 Unity Catalog 进行治理，并由无服务器计算和 Lakeflow Spark Declarative Pipelines 提供支持。

请记住以下三点：

• 简单且易于维护——无需编写客户端代码，也无需运维消息总线；只需连接器 + UC Connection + 无服务器管道。
• 与 lakehouse 统一——凭据存储在 UC 中，输出为受治理的 Delta，并像其他工作负载一样在 Jobs 和 SDP 上运行。
• 高效的增量处理——内置变更跟踪 / CDC / 架构演进 / 重试。

共有四种架构模式：

1. SaaS 拉取——连接器通过 OAuth 或 API 密钥从外部 SaaS 读取数据，并将其写入流式 Delta 表。
2. 通过网关进行数据库 CDC——摄取网关在客户网络中运行，将变更事件暂存到 UC Volume，无服务器摄取管道再将其作为 CDC 应用到 Delta 中。
3. 基于查询——适用于没有原生 CDC 的数据源（Oracle / Teradata / SQL Server / PG / MySQL 基于查询的连接器，以及通过 Foreign Catalog 连接的 Snowflake / Redshift / Synapse / BigQuery）；连接器会定期发起查询，而非订阅变更流。
4. 社区连接器——基于模板，不属于本技能的范围。

---

Lakeflow Connect 是合适的工具吗？

在构建之前先做出判断。Lakeflow Connect 是面向 SaaS 应用和数据库的托管式拉取路径——它并不适用于所有摄取需求。

如果数据源是……	使用	技能
有托管连接器的 SaaS 应用或数据库（Salesforce、Workday、ServiceNow、GA4、HubSpot、Confluence、SQL Server 等）	Lakeflow Connect	本技能
云对象存储上的文件（S3 / ADLS / GCS）	Auto Loader	databricks-pipelines
想要原地查询而不复制的数据源	Lakehouse Federation	—
向你推送事件的应用或设备	Zerobus	databricks-zerobus-ingest
提供 Delta 共享的合作伙伴	Delta Sharing	—

关于 Federation 与 Connect、Auto Loader 与 Connect 之间取舍的完整说明，请参阅 4-ingestion-decision-tree.md。

---

连接器目录

Lakeflow Connect 提供多个发布阶段的连接器。GA 和 Public Preview 连接器支持用于生产环境；Beta 和 Private Preview 连接器面向早期体验，不支持用于生产环境。

GA 连接器

本技能已提供完整覆盖，Reference 为公共文档页面的行除外。

来源	类型	身份验证	参考资料
Salesforce（Sales / Service / 等）	SaaS 拉取	OAuth U2M	1-saas-connectors.md
Workday Reports（RaaS）	SaaS 拉取	OAuth refresh token / basic	1-saas-connectors.md
ServiceNow	SaaS 拉取	OAuth U2M / basic	1-saas-connectors.md
Google Analytics 4	SaaS 拉取（通过 BigQuery）	Service-account JSON	1-saas-connectors.md
HubSpot	SaaS 拉取	OAuth	1-saas-connectors.md
Confluence	SaaS 拉取	OAuth	1-saas-connectors.md
NetSuite	SaaS 拉取	基于令牌的身份验证（TBA）	NetSuite connector docs
Dynamics 365	SaaS 拉取（通过 Azure Synapse Link）	OAuth U2M	Dynamics 365 connector docs
SQL Server（云端）	数据库 CDC	DB 用户 + change tracking / CDC	2-database-connectors.md
SQL Server（本地部署）	数据库 CDC	DB 用户 + ExpressRoute / Direct Connect	2-database-connectors.md
MySQL（集成式 CDC 管道，无网关）	数据库 CDC	DB 用户	MySQL integrated CDC pipeline docs
Oracle / Teradata / SQL Server / PG / MySQL（基于查询）	数据库查询	DB 用户	Query-based connectors docs
Snowflake / Redshift / Synapse / BigQuery（Foreign Catalog）	数据库查询	Foreign Catalog	Query-based connectors docs

公共预览版连接器

支持生产环境。正式发布前，配置可能会有所调整。详细覆盖内容将逐步补充；在此之前，请参阅公共连接器参考了解当前设置步骤。

来源	类型	身份验证
PostgreSQL CDC	数据库 CDC	DB 用户 + 网关
MySQL CDC（基于网关）	数据库 CDC	DB 用户 + 网关
SFTP	文件拉取	密钥 / 密码

Beta 版和私有预览版

早期访问连接器不支持生产环境。列表每月都会变化；请查看公共连接器参考了解当前可用情况。

关于 Lakeflow-Connect-vs-Auto-Loader-vs-Federation-vs-Delta-Sharing 的选择，请参阅 4-ingestion-decision-tree.md。

---

所需工具

• Databricks CLI v0.294.0+，用于 databricks pipelines create 和 databricks connections create。使用 databricks --version 进行验证。
• Databricks SDK for Python（databricks-sdk>=0.85.0），如果你更倾向于使用 SDK 而非 CLI。
• 如果以 IaC 方式编写（建议用于任何要部署到客户环境的管道），请使用 Declarative Automation Bundles。

无需额外的连接器专用 SDK。Lakeflow Connect 复用 pipelines API 接口——创建管道时使用 ingestion_definition 块，而不是 libraries 块；除此之外，API 和 CLI 均相同。

---

前提条件

创建任何管道之前，请确认：

1. Unity Catalog 目标 — catalog 和 schema 必须已存在；创建管道的服务主体或用户需要对目标 schema 拥有 USE CATALOG、USE SCHEMA、CREATE TABLE 和 MODIFY 权限。
2. 带有源凭据的 UC CONNECTION 对象。SaaS OAuth U2M 连接必须通过 UI（Catalog Explorer）创建；API 密钥和基本身份验证连接可通过 CLI / DAB 创建。
3. 对于数据库连接器：网关（经典计算，客户 VPC）与源数据库之间必须网络可达。本地部署需要 ExpressRoute（Azure）或 Direct Connect（AWS）。
4. 对于文件连接器：必须在 SaaS 文件存储库（SharePoint / Google Drive）上授予 OAuth 范围。

---

最简示例 — Salesforce 数据摄取管道

规范的创作路径是将 JSON 传递给 databricks pipelines create --json。（Lakeflow Connect 没有 SQL CREATE TABLE … FROM CONNECTION 语法——该语法仅适用于 Lakehouse Federation，这是另一款产品。）

databricks pipelines create --json '{
  "name": "salesforce_to_uc",
  "ingestion_definition": {
    "connection_name": "my_salesforce_oauth_connection",
    "objects": [
      {"table": {"source_schema": "salesforce", "source_table": "Account",
                 "destination_catalog": "main", "destination_schema": "salesforce_raw"}},
      {"table": {"source_schema": "salesforce", "source_table": "Opportunity",
                 "destination_catalog": "main", "destination_schema": "salesforce_raw"}}
    ]
  }
}'

生产环境的 DAB 创作版本请参阅 1-saas-connectors.md。

---

运行管道

创作完成后，部署并触发一次运行。使用 Bundle 路径可通过键运行，命令也最简洁：

databricks bundle deploy -t dev
databricks bundle run salesforce_ingestion           # KEY = the pipeline resource key in the bundle; waits by default
databricks bundle run salesforce_ingestion --no-wait

通过 pipelines create --json 命令式创建的管道没有按名称运行的 CLI 命令——请改用管道 ID 启动更新并轮询其状态：

databricks pipelines start-update <pipeline-id>             # returns an update_id
databricks pipelines get-update  <pipeline-id> <update-id>  # poll one update's status
databricks pipelines list-updates <pipeline-id>             # recent updates and their states

这种不对称也是使用 Declarative Automation Bundle 进行创作的另一个理由。

---

详细指南

主题	文件	阅读时机
SaaS 连接器（Salesforce、Workday Reports、ServiceNow、GA4、HubSpot、Confluence）	1-saas-connectors.md	统一的 SaaS 模式、各连接器的差异、OAuth 流程、DAB 模板
数据库连接器（云端和本地 SQL Server）	2-database-connectors.md	网关模式、变更跟踪与 CDC、网络设置
数据摄取决策树	4-ingestion-decision-tree.md	Lakeflow Connect、Auto Loader、Lakehouse Federation 与 Delta Sharing 的比较
故障排查与监控	5-troubleshooting-and-monitoring.md	事件日志查询、常见错误、升级处理指引

---

工作流

每创建一条新的数据摄取管道：

1. 选择连接器类别——SaaS / 数据库 / 文件 / 推送，并阅读相应的参考文件。
2. 验证前提条件——UC 目标、源凭据、网络路径（针对数据库）和区域可用性。
3. 创建 UC CONNECTION——OAuth U2M 使用 UI，其他情况使用 CLI / DAB。
4. 创作管道——临时任务使用 databricks pipelines create --json；任何将交付给客户的内容都使用 DAB YAML。
5. 触发首次运行并查看事件日志；SQL 语句请参阅 5-troubleshooting-and-monitoring.md。
6. 通过 Jobs pipeline_task 为已触发的管道安排计划（cron 或间隔）。Lakeflow Connect 仅支持触发式运行——continuous: false 用于选择触发模式，但它本身并非计划；运行频率由 Jobs 触发器决定。

---

反模式

以下三种写法看似可行，实际上会失败——错误写法与正确写法：

1. CREATE TABLE ... FROM CONNECTION 属于 Lakehouse Federation，不属于 Lakeflow Connect。

-- WRONG: Federation syntax; no LFC equivalent exists
CREATE TABLE main.salesforce_raw.account FROM CONNECTION my_salesforce_conn;

// RIGHT: author an ingestion_definition (see the Minimal Example above)
{"ingestion_definition": {"connection_name": "my_salesforce_conn", "objects": [/* ... */]}}

2. 数据摄取管道使用 ingestion_definition，绝不包含 libraries 块。

// WRONG: libraries is for a standard SDP pipeline running your notebooks/files
{"name": "salesforce_to_uc", "libraries": [{"notebook": {"path": "/Repos/.../ingest"}}]}
// RIGHT:
{"name": "salesforce_to_uc", "ingestion_definition": {"connection_name": "...", "objects": []}}

3. 不接受 continuous: true——Lakeflow Connect 仅支持触发式运行。

// WRONG: continuous mode fails at create
{"continuous": true, "ingestion_definition": {/* ... */}}
// RIGHT: continuous:false (or omit) + schedule with a Jobs pipeline_task
{"continuous": false, "ingestion_definition": {/* ... */}}

---

重要事项

• 仅触发运行，不支持连续模式——管道按计划或按需运行，不会持续运行。请查看连接器参考，了解最新状态。
• 仅按计算资源计费——Lakeflow Connect 按 DBU 计费（不按行收费）。除无服务器摄取管道的 DBU 外，数据库连接器还会产生经典计算网关 DBU。当前费率请参阅定价页面。
• Salesforce 仅支持 OAuth U2M 身份验证——不支持机器对机器身份验证，也不支持基本身份验证。创建连接需要通过 UI 完成操作。
• 数据库暂存数据默认保留 30 天，存放在网关与摄取管道之间的 UC Volume 中。
• 每个管道的限制——大多数 SaaS 连接器每个管道最多支持 250 个表。如有需要，请拆分到多个管道。
• 此功能会写入原始表——Lakeflow Connect 会写入忠实反映源数据的表（摄取暂存区）。请使用 databricks-pipelines 在这些表的基础上构建 Medallion Bronze/Silver/Gold 转换。

---

核心概念

• UC CONNECTION 是凭据锚点——每个 Lakeflow Connect 管道都指向一个 UC 连接。连接负责管理身份验证；管道通过名称引用该连接。
• 无服务器摄取管道 +（可选）经典网关——SaaS 连接器完全使用无服务器架构。数据库连接器则拆分为客户网络中的网关（经典计算）和无服务器摄取管道（绑定到 Delta）。
• 内置 CDC 和架构演进——对于支持变更跟踪或 CDC 的数据源，连接器会增量应用变更并演进目标架构。数据类型变更通常需要重新加载完整快照。
• 流式 Delta 输出——目标表是受治理的 Delta 表；CDC 数据源会按照变更语义应用变更（APPLY CHANGES / AUTO CDC；对于快照数据源，则使用 apply_changes_from_snapshot）。兼容下游物化视图和 Spark 流处理。
• OAuth U2M 仅可通过 UI 设置——DAB / CLI 无法初始化 OAuth U2M 连接。请将一次性的浏览器操作交给人工完成（Catalog Explorer > External Data > Connections > Create connection > 选择数据源 > 登录），然后等 databricks connections get <connection_name> 报告 READY 后继续。

---

常见问题

如需了解常见错误及其解决方法——包括重复键冲突、水位线 / 游标问题、架构演进、网关区域可用性、channel 运行时通道设置，以及管道运行但未写入数据等问题——请参阅 5-troubleshooting-and-monitoring.md，其中还包含用于诊断问题的事件日志查询。

---

相关技能

• databricks-pipelines——Lakeflow Connect 管道所运行的 SDP 运行时。适用于 Auto Loader 和下游管道模式。
• databricks-zerobus-ingest——基于推送的 gRPC 摄取，是 Lakeflow Connect 基于拉取的连接器的同类工具。
• databricks-dabs——将 Lakeflow Connect 管道编写为 IaC。
• databricks-unity-catalog——管理目录、架构，以及存放 LFC 凭据的 UC CONNECTION 对象。
• databricks-jobs——使用 pipeline_task 安排摄取管道。

---

资源

• Lakeflow Connect 公共文档中心
• 连接器参考（各连接器的设置说明）
• 定价