dbt ETLパイプラインの接続先をDatabricksに変更する方法

より多くのチームが、ロックインのないオープンなプラットフォーム、統合されたパイプライン、組み込みの Unity Catalog ガバナンス、および優れた価格性能比を備えた Databricks Lakehouse上で dbt トランスフォーメーションを実行しています。

お使いの dbt プロジェクトは正常に動作します。モデルはコンパイルされ、テストはパスし、トランスフォーメーションロジックは特定のウェアハウスにハードコードされることなく、バージョン管理された SQL と YAML に保存されます。dbt のオープンなアダプターフレームワークは、まさにこの疎結合のために設計されているため、あるクラウドデータウェアハウスから別のクラウドデータウェアハウスへの移行は、アダプターと接続設定を変更し、いくつかのダイアレクト（方言）を微調整するだけで済み、DAG やビジネスロジックを書き直す必要はありません。

Databricks は、共同開発された dbt-databricks アダプター、オープンなレイクハウスストレージ（Delta Lake および Apache Iceberg™）、 Unity Catalog、そして Lakeflow Jobs によってそれを実現します。これにより、初日から組み込みのガバナンスと優れた価格性能比で dbt を実行できる、オープンで統合されたプラットフォームが提供され、 dbt ワークロードを実行するのに最適な環境となります。これが、すでに 3,000 以上の組織が Databricks 上で dbt を実行している理由です。

移行を検討されている方に朗報です。プロジェクトを再構築する必要はありません。このブログ記事では、アダプターとプロファイルを切り替え、いくつかの SQL の違いに対応し、トランスフォーメーションロジックを dbt 内に維持したまま、稼働中の dbt プロジェクトの接続先を Databricks に変更する方法を順を追って説明します。

dbt の接続先変更が移行の強力なスタート地点となる理由

データウェアハウスの移行プロジェクトでよくある課題は、すべてを一度に移動しようとすることです。これにより、遅延やボトルネックが発生する可能性があります。より優れたアプローチは、トランスフォーメーションレイヤーから始めることです。これは、移行によるコスト削減を迅速に実現するための近道です。

dbt プロジェクトはすでにモジュール化されており、テスト可能です。そのため、段階的な移行に最適です。dbt の接続先を Databricks に変更すると、以下のメリットが得られます。

• 即時の検証。古いウェアハウスと新しいウェアハウスの出力をモデルごとに比較できます
• リスクの低減。 トランスフォーメーションロジックは変更されないため、変数をコンピュートとストレージのみに限定できます
• 実用的な概念実証（POC）。インジェスチョン（取り込み）レイヤーや BI レイヤーを移行する前に、関係者は Databricks 上でクエリが実行されているのを確認できます
• 価値実現までの時間を短縮。 技術スタック全体を一度に移行するのではなく、まずトランスフォーメーションレイヤーを移行します

前提条件

範囲：このガイドでは、dbt トランスフォーメーションレイヤーの接続先変更のみを扱います。ソースデータがすでに Databricks に存在し（Delta または Iceberg テーブルとして格納され、Unity Catalog に登録されている）、カタログとスキーマが存在していることを前提としています。データ自体の移行と Unity Catalog のセットアップは別の作業です。これらについては、Databricks の移行ガイドおよび Lakebridge を参照してください。

開始する前に、以下が準備されていることを確認してください。

• SQL ウェアハウスがプロビジョニングされた Databricks ワークスペース
• ターゲットカタログとスキーマが作成された Unity Catalog のセットアップ、および Delta または Iceberg としてすでに格納され UC に登録されているソース（raw/bronze）テーブル
• バージョン管理されている既存の dbt プロジェクト（dbt Core 1.8+ または dbt Platform）
• ローカルにインストールされた Python 3.9+（dbt Core ユーザー向け）
• アクセス資格情報：Databricks 個人用アクセストークンまたは OAuth 設定
• オプションとして、 Lakebridge を使用して SQL 変換の大部分を自動化できます。Lakebridge は、ソースウェアハウスと dbt モデル内の SQL をスキャンし、ダイアレクト固有の SQL を Databricks Lakehouse に変換し、その結果をソースと照合します。dbt 自体を移行するのではなく、dbt プロジェクト内の SQL の接続先を変更します。また、別のパターン（Lakehouse Federation + CTAS、COPY INTO、または Auto Loader）を使用するデータは移動しません。

この例で移行するモデルは、2 つのソースモデル（ orders と order_items）の上に構築された標準的な分析ファクトテーブルです。これは、注文レベルのデータを集計して総売上高を計算し、過去 1 年間の個々の取引ごとに販売された製品のリストをまとめます。 

このモデルは、 regexp_substr、 div0、 object_construct など、データウェアハウス間で異なることが多い、いくつかの一般的な SQL ダイアレクトパターンを使用しているため、最適な例となっています。ここでのこれらのパターンの処理方法を理解すれば、プロジェクト内の他のすべてのモデルに同じアプローチを適用できます。

ステップ 1：アダプターのインストールと Databricks ターゲットの追加

このパートでは、アダプターのインストール、ネームスペースのマッピング、ダイアレクトの違いの処理など、1 回限りの移行作業について説明します。

dbt-databricks アダプターのインストール

 dbt-databricks アダプターは、dbt プロジェクトと Databricks Lakehouse ウェアハウスの間の架け橋となります。dbt のコンパイル済み SQL を Databricks 互換のクエリに変換します。

（dbt Platform ユーザーの場合： dbt ドキュメントに記載されているように、新しい環境で接続タイプとして「Databricks」を選択します。アダプターは自動的にインストールされます。）

`profiles.yml` に Databricks ターゲットを追加します。既存のターゲットはそのまま残しておきます（検証時に必要になります）。その横に 2 つ目のターゲットを追加します。

接続を確認する：

以下が表示されるはずです。  Connection test: [OK connection ok].

それでも接続できない場合は、Databricks + dbt 統合ガイドおよびdbt Databricks プロファイルリファレンスにある接続のトラブルシューティング手順に従ってください。

プロのヒント： http_pathは、クエリを SQL ウェアハウス（dbtに推奨）で実行するか、汎用クラスターで実行するかを決定します。SQL ウェアハウスは、SQL主体のワークロードに対して優れた費用対効果を提供します。

ステップ 2：テーブルソースを Unity Catalog に指定し、テストを追加する

Databricks は3レベルの名前空間（ catalog.schema.table）を使用します。fct_ordersが読み取る sources.yml のエントリを更新します。

テストを含めるように schema.yml を更新します

プロのヒント： database:をスキップすると、クエリはワークスペースのデフォルトカタログに配置されます。明示的に設定してください。

ステップ 3：最初のコンパイル

次に、モデルに対して dbt compile を実行します。

作成した fct_orders モデルでは、以下に示すように3つのコンパイルエラーが発生しました。これらはすべて方言（ダイアレクト）に関連するものです。これは想定内の動作です。これら3つのエラーはほとんどのプロジェクトで発生する方言の問題を代表するものですが、すべてではありません。より大規模な移行では、インクリメンタルモデル戦略、スナップショット、直接対応するものがない半構造化関数などにも直面します。 

ここでは、位置パラメータを持つ REGEXP_SUBSTR、安全な除算のための DIV0、JSON 構築のための OBJECT_CONSTRUCT など、ウェアハウス間で異なる方言特有のパターンに依存するサンプルモデルを意図的に使用しています。そうすることで、最初の dbt run エラーが変換プロセスのガイドとなり、これらをポータブルなマクロや Databricks に適した SQL に変換する方法を示し、プロジェクトの他の部分にも同じ修正を適用できるようになります。デモとして、各エラー、根本原因、および修正方法を順を追って説明します。エラーについて詳しく説明する前に、ポータビリティ（移植性）について一言。関数にポータブルな代替手段がある場合、dbt のクロスデータベースマクロ（dbt.* 名前空間）を使用すると、1回記述するだけで任意のウェアハウスでコンパイルできるようになります。標準化を進めるにあたって採用する価値があります。各エラーとその修正方法を説明した後、大規模なプロジェクト全体でこの変換を自動化する方法を紹介します。

エラー 1： REGEXP_SUBSTR の方言の不整合

Databricks は Apache SQL 方言に従っており、 REGEXP_SUBSTR に対しては2つのパラメータのみをサポートしています。

修正方法：Databricks ネイティブの regexp_extract() 関数を使用します

Genie Code にこの変換を任せることもできます。このような方言のギャップを修正することは、まさに Genie Code が得意とする分野です。ここでは、何が変更されるかを確認できるように、3つすべてを手動で実行します。

エラー 2：DIV0（安全な除算）

根本原因：一部のウェアハウスでは、ゼロ除算の際にエラーをスローする代わりに 0 を返すために DIV0 を使用します。

修正方法：packages に dbt_utils を追加し、その組み込みの safe_divide 関数を使用します

エラー 3：object_construct（JSON ビルダー）

ルーチン `object_construct` を解決できません

修正方法：Databricks の named_struct 関数を使用します

コンパイルの再実行：

正常にコンパイルされました。このモデルに対する方言の変更の合計： dbt_utils package installed（安全な除算用）、 regexp_substr call converted to regexp_extract、 div0 の呼び出しを dbt_utils.safe_divide() に置換、 object_construct call converted から named_struct へ。

3つの関数を手動で修正するのは簡単です。しかし、実際の dbt プロジェクトには数百から数千のモデルがあり、このような方言のギャップこそが AI ツールによって自動的に解消されるものです。Genie Code は方言特有の SQL を変換し、エディタ内で直接これらの修正を処理するため、各修正を記述する代わりに変換内容の確認に時間を費やすことができます。

ステップ 4：最初の実行

コンパイルが成功したら、モデルと存在するテストを実行します。

モデルのビルドとテストの両方に合格しました。 プロのヒント：

• 実行時間。メモしておいてください。次のステップで古いウェアハウスと比較します。
• 数値列でのテストの失敗。equality または accepted_values のテストが失敗する場合、そのほとんどはロジックのバグではなく、浮動小数点数の精度によるものです。

ステップ 5：レガシーウェアハウスに対して行単位で検証する

緑色の dbt run は SQL が実行可能であることを証明します。次に、レガシーウェアハウスと Databricks の間で出力を一致させる必要があります。行単位で比較するには dbt-audit-helper を使用します。

インストール：

両方のウェアハウス間で fct_orders を比較します。analyses/compare_fct_orders.sql 内：

Databricks に対して実行します（比較のためにレガシー出力を Databricks に複製済みであるか、クロスウェアハウス比較を実行することを想定しています）：

期待される結果：

注意：これらの例は最も一般的なパターンをカバーしていますが、すべてを網羅しているわけではありません。その他の不一致（文字列のトリミング、照合順序、カスタム UDF の動作など）については、summarize=false を設定してサンプル行を実体化し、in_a と in_b が異なるいくつかの主キーを検査し、モデルまたはマクロを修正して、100% 一致するまで再実行します。

今回の実行では、fct_orders が完全に一致しました。

ステップ 6：Databricks にデプロイする

dbt 用に個別のオーケストレーション層を維持する代わりに、Lakeflow Jobs を使用して、単一のパイプライン内でアップストリームのインジェストやダウンストリームのアクションと並行して dbt を実行できます。dbt は Jobs 内のファーストクラスのタスクタイプであり、外部のオーケストレーターやカスタムの Docker イメージは必要ありません。

ジョブの作成：

1. ワークスペース → ジョブとパイプライン → ジョブを作成
2. タスクタイプ：dbt
3. Git ソース：お使いの dbt リポジトリ
4. コマンド：

5. SQL ウェアハウス：本番環境のウェアハウス
6. ウェアハウスのカタログ：テーブルが書き込まれるカタログ：dev
7. ウェアハウスのスキーマ：テーブルが書き込まれるスキーマ：analytics
8. スケジュール：ご希望の頻度

Jobs が標準で提供するもの：

• 完全マネージド — 追加のインフラストラクチャの購入、セキュリティ保護、メンテナンスは不要
• アップストリームのインジェストパイプラインや、Power BI の更新などのダウンストリームのタスクと並行して dbt タスクを実行する単一のパイプラインを作成可能

ステップ 7：切り替えと廃止

dbt プロジェクトを検証して Databricks にデプロイしたら、次のステップは、制御された方法で本番トラフィックを Databricks に移行し、迅速なロールバック経路を確保し、必要以上に長く 2 つのウェアハウスに料金を支払うのを避けることです。

以下のチェックリストを確認してください：

1. profiles.yml 内の本番ターゲットを切り替えて prod が Databricks を指すようにします。これにより、すべての新しい本番実行が Databricks に書き込まれるようになります。
2. CI/CD の認証情報を更新し、PR のチェックがレガシーウェアハウスではなく、Databricks のステージングカタログに対して実行されるようにします。
3. system.billing.usage を通じてコストを監視し、Databricks の支出プロファイルを確認します。
4. ロールバック期間が終了し、Databricks が本番環境で安定して動作していることを確認できたら、レガシーターゲットを廃止します。

プロジェクトの残りの部分への拡張

これまでに行った作業のほとんどは、アダプターのインストール、profiles.yml ターゲット、ソースの名前空間の変更など、1 回限りのものです。これらが整えば、次のモデルの参照先を変更するのにかかるコストは、増分の方言（ダイアレクト）の修正のみになります。

規模を拡張するにつれて、方言の入れ替え以上の対応が必要なパターンに遭遇することがあります。

• インクリメンタルモデル — インクリメンタル戦略はプラットフォームによって異なります。移行元の戦略が Databricks のインクリメンタル戦略と 1 対 1 で対応しない場合があるため、戦略を再選択し、インクリメンタルロジックを再検証する必要があります。
• スナップショット — スナップショットのロジックの参照先を変更し、それとは別に、履歴を失わないように既存の履歴スナップショットデータを移行します。
• 半構造化データおよびニッチな関数 — 一部の移行元の関数には Databricks に直接対応するものがなく、1 行の変更ではなく、書き換えやマクロが必要になる場合があります。

ここでの複雑な作業については、完全な移行ガイドを参考にしてください。

そこからは、小さなバッチで移行し、DAG の順序（最初にソース、次にステージング、中間、マート）で作業を進めることで、各バッチがすでに移行済みのモデルに対して正常に検証されるようにします。両方のターゲットを並行して実行し、audit-helper を使用して、すべてが一致するまで各モデルを比較します。最後のモデルが正常（グリーン）になったら、プロジェクト全体を切り替えます。このガイドは参照先変更の簡略化されたチュートリアルであり、移行の全範囲は弊社の公開移行ガイドでカバーされています。

まとめ

dbt の参照先を Databricks に変更することは、ウェアハウスの移行を開始するための実用的でリスクの低い方法です。モデルとテストはそのまま維持され、実行場所を変更するだけで、Delta Lake や Apache Iceberg™ などのオープンソースのフォーマットや標準を利用できるようになります。さらに、Unity Catalog がガバナンスとリネージを提供し、ダウンストリームの AI ワークにも対応できるプラットフォームを構築できます。まずは 1 つのモデルから始めて出力を比較し、Databricks を dbt プロジェクトのメイン環境として安心して使用できるようになるまで拡張していきましょう。

試してみる準備はできましたか？

1. Databricks の無料トライアルを設定する
2. dbt-databricks アダプターをインストールする
3. Databricks レイクハウスウェアハウスに対して最初の dbt コンパイルを実行します。その後、Databricks のドキュメントに従って、本番環境で dbt モデルを実行するための Databricks ジョブをデプロイします。

Databricks での dbt の詳細については、GitHub の dbt-databricks アダプターをご覧ください。

(このブログ記事はAI翻訳ツールを使用して翻訳されています) 原文記事