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 によって実行されます。

次の 3 つの点を押さえておきましょう。

• シンプルでメンテナンスが容易 — クライアントコードの記述も、メッセージバスの運用も不要です。コネクター、UC Connection、サーバーレスパイプラインを用意します。
• レイクハウスと統合 — 認証情報は UC に保存され、出力はガバナンスが適用された Delta となり、ほかのワークロードと同様に Jobs と SDP 上で実行されます。
• 効率的な増分処理 — 変更追跡、CDC、スキーマ進化、再試行が組み込まれています。

アーキテクチャパターンは 4 つあります。

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 share を提供するパートナー	Delta Sharing	—

Federation と Connect、Auto Loader と Connect の比較を含む詳しい判断方法は、4-ingestion-decision-tree.md を参照してください。

---

コネクターカタログ

Lakeflow Connect では、複数のリリース段階のコネクターが提供されています。GA と Public Preview のコネクターは本番環境でサポートされています。Beta と Private Preview のコネクターは早期アクセス向けであり、本番環境ではサポートされていません。

GA コネクター

Reference が公開ドキュメントページの行を除き、このスキルで完全に網羅しています。

Source	Type	Auth	Reference
Salesforce（Sales／Service など）	SaaS プル	OAuth U2M	1-saas-connectors.md
Workday Reports（RaaS）	SaaS プル	OAuth リフレッシュトークン／ベーシック	1-saas-connectors.md
ServiceNow	SaaS プル	OAuth U2M／ベーシック	1-saas-connectors.md
Google Analytics 4	SaaS プル（BigQuery 経由）	サービスアカウント JSON	1-saas-connectors.md
HubSpot	SaaS プル	OAuth	1-saas-connectors.md
Confluence	SaaS プル	OAuth	1-saas-connectors.md
NetSuite	SaaS プル	トークンベース認証（TBA）	NetSuite コネクターのドキュメント
Dynamics 365	SaaS プル（Azure Synapse Link 経由）	OAuth U2M	Dynamics 365 コネクターのドキュメント
SQL Server（クラウド）	データベース CDC	DB ユーザー＋変更追跡／CDC	2-database-connectors.md
SQL Server（オンプレミス）	データベース CDC	DB ユーザー＋ExpressRoute／Direct Connect	2-database-connectors.md
MySQL（ゲートウェイ不要の統合 CDC パイプライン）	データベース CDC	DB ユーザー	MySQL 統合 CDC パイプラインのドキュメント
Oracle／Teradata／SQL Server／PG／MySQL（クエリベース）	データベースクエリ	DB ユーザー	クエリベースコネクターのドキュメント
Snowflake／Redshift／Synapse／BigQuery（Foreign Catalog）	データベースクエリ	Foreign Catalog	クエリベースコネクターのドキュメント

パブリックプレビューのコネクター

本番環境でサポートされています。GA までに設定が変更される場合があります。詳細な説明は順次追加されています。それまでは、現在のセットアップ手順について公開コネクターリファレンスを参照してください。

Source	Type	Auth
PostgreSQL CDC	データベース CDC	DB ユーザー＋ゲートウェイ
MySQL CDC（ゲートウェイベース）	データベース CDC	DB ユーザー＋ゲートウェイ
SFTP	ファイルプル	キー／パスワード

ベータ版およびプライベートプレビュー

早期アクセスのコネクターは、本番環境ではサポートされていません。リストは毎月変更されます。現在の提供状況については、公開コネクターリファレンスを確認してください。

Lakeflow Connect と Auto Loader、Federation、Delta Sharing の選択については、4-ingestion-decision-tree.mdを参照してください。

---

必要なツール

• databricks pipelines create と databricks connections create の実行には、Databricks CLI v0.294.0+ が必要です。databricks --version で確認してください。
• CLI より SDK を使いたい場合は、Databricks SDK for Python（databricks-sdk>=0.85.0）が必要です。
• IaC として作成する場合は、Declarative Automation Bundles が必要です（顧客環境にデプロイするパイプラインでは推奨）。

コネクター固有の SDK を追加する必要はありません。Lakeflow Connect はパイプライン API を再利用します。パイプラインは libraries ブロックではなく ingestion_definition ブロックを使って作成しますが、それ以外は API と CLI は同じです。

---

前提条件

パイプラインを作成する前に、以下を確認してください。

1. Unity Catalog のターゲット — カタログとスキーマが存在している必要があります。パイプラインを作成するサービスプリンシパルまたはユーザーには、ターゲットスキーマに対する 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 を参照してください。

---

パイプラインの実行

作成したら、デプロイして実行を開始します。バンドルのパスを使うと、キーを指定して実行するコマンドを最も簡潔に記述できます。

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 のトリガーで設定します。

---

避けるべきパターン

一見もっともらしくても失敗するパターンが3つあります。誤った例と正しい例を示します。

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 を使って、メダリオンアーキテクチャの 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 の公開ドキュメントハブ
• コネクターのリファレンス（コネクターごとのセットアップ）
• 料金