DABsってDatabricks Asset Bundlesだと思っていたら、いつの間にかDatabricks Declarative Automation Bundlesになっていたので実践してみた

DABsといえば、Databricks Asset Bundlesだと思っていました。

ところが、公式ドキュメントを開くと、今はDeclarative Automation Bundlesと書かれています。しかも、旧称としてDatabricks Asset Bundlesが併記されていました。略称は見慣れているのに、正式名称はいつの間にか変わっていたようです。

名前を確認したのをきっかけに、何をまとめて管理できるのか、改めて整理します。今回はDatabricksの画面からバンドルを作り、生成された設定ファイルを読み解くところから始めます。

DABsは何をまとめる仕組みなのか

DABsは、Databricks上で動かす処理と、その処理を動かすための設定を、一つのプロジェクトとして管理する仕組みです。

例えば、SQLやPythonのコードだけがGitに入っていても、ジョブのタスク構成やパイプラインの保存先が画面上にしか残っていないと、別の環境へ移す際に設定を再現する必要があります。コードは同じなのに、設定だけが違うという状態も起こり得ます。

バンドルでは、こうしたリソースの定義をコードと一緒に管理できます。ノートブック、ジョブ、Lakeflowパイプラインに加え、ダッシュボードやモデル関連のリソースも対象です。変更をGitで追い、レビューしてからデプロイする流れにつなげられます。公式の概要でも、ソース管理やテスト、CI/CDをデータ・AIプロジェクトへ取り入れるための仕組みとして説明されています。

Gitで管理するプロジェクト
  ├─ SQL・Python・ノートブック：何を処理するか
  ├─ ジョブ・パイプラインの定義：どう動かすか
  └─ デプロイ先ごとの設定：どこへ配置するか
                  │
                  ▼ 検証・デプロイ
           Databricksのリソース
                  │
                  ▼ 実行
             データの処理結果

以前触ったLakeflow SDPと組み合わせるなら、SDPがデータ変換を定義し、DABsがそのパイプラインの設定や配置を管理する、と考えると役割を整理しやすいです。

今回の到達点と準備

今回は、GitHubのリポジトリをDatabricksのGitフォルダーとして取り込み、Lakeflowパイプラインのテンプレートからバンドルを作成します。まずは開発用のdevにデプロイし、生成されたファイルとリソースの対応を確認することが到達点です。サンプルの実行確認まで進める場合の手順も後半に載せます。

利用するものは次のとおりです。

ワークスペースのUIを使う方法では、ローカルPCへのDatabricks CLIのインストールは不要です。ワークスペースでの利用要件を確認してから進めます。

1. GitHubのリポジトリとGitフォルダーを用意する

GitHubで検証用のリポジトリを作成します。ここではリポジトリ名をdabs-practiceとして、README.mdも追加して作成します。

次に、DatabricksとGitHubを連携します。未設定の場合は、ユーザー設定のSettings → Linked accounts → Add Git credentialからGitHubを選び、Link Git accountで連携します。GitHub.comでは、Databricks GitHub Appを使う方法が公式に推奨されています。今回のリポジトリをAppのアクセス対象に含めてください。Gitプロバイダーとの接続手順に詳細があります。

連携できたら、Databricks側で次の操作を行います。

1. Workspaceで、Gitフォルダーを作成する場所を開きます。
2. Create → Git folderを選びます。
3. GitHubリポジトリのHTTPS URLを入力します。今回の画面では、Git providerとフォルダー名は自動入力されました。
4. フォルダー名を確認し、Create Git folderで作成します。
5. 作成したフォルダーを開き、READMEが見えることを確認します。

入力するURLはhttps://github.com/<ユーザー名>/dabs-practice.gitの形式です。トークンをURLに埋め込む必要はありません。作成場所の権限などはGitフォルダーの公式手順を参照してください。

2. Gitフォルダー内にバンドルを作成する

ここでのポイントは、Gitフォルダーの中から作成することです。通常のワークスペースフォルダーでBundleが選べない場合は、現在の場所を確認します。

Gitフォルダーを開き、Create → Bundleを選びます。バンドル名にはdabs_practiceを指定しました。GitHubのリポジトリ名dabs-practiceとは、ハイフンとアンダースコアが異なります。

作成画面では、空のプロジェクトや、Python、SQL、Lakeflowパイプラインなどのテンプレートを選択します。今回はLakeflowパイプライン用のテンプレートを使います。画面の選択肢や表記は更新されるため、実際に表示される説明も確認してください。

続く設定では、次のように指定します。

workspaceは例です。画面に表示されるカタログと自分の権限に合わせて選びます。今回はSQLを選びますが、Pythonを選ぶ場合でも、バンドル全体を管理する考え方は共通です。

設定を確認し、Create and deployへ進みます。デプロイの確認画面が表示された場合は、対象がdevであることと、作成されるリソースを確認します。基本的な作成操作はワークスペースでのバンドル作成チュートリアルも参考になります。

3. 生成されたファイルの役割を確認する

バンドルができたら、最初にファイル構成を確認します。細かいファイル名はテンプレートによって変わりますが、見る場所は大きく三つです。

dabs_practice/
├─ databricks.yml       # バンドル全体の設定
├─ AGENTS.md            # AIコーディングツール向けの指示
├─ CLAUDE.md            # Claude Code向けの指示
├─ README.md            # バンドルの説明
├─ resources/           # ジョブやパイプラインの定義
│  ├─ *.job.yml
│  └─ *.pipeline.yml
└─ src/                 # 実際に動かす処理
   └─ dabs_practice_etl/
      ├─ explorations/
      └─ transformations/
         └─ *.sql

これは主要な部分だけを示した構成例です。開発環境向けの設定ファイルが追加される場合もあります。パイプライン用バンドルの公式解説にも、生成ファイルとそれぞれの役割がまとまっています。

余談ですが、今回のテンプレートではAGENTS.mdとCLAUDE.mdも生成されました。時代を感じますね。

resourcesには、パイプラインの設定や、そのパイプラインを起動するジョブの定義が入ります。srcには、SQLやPythonで書くデータ変換処理が入ります。この2つのフォルダとdatabricks.ymlが重要です。

同じ「パイプラインに関するファイル」でも、保存先や実行設定を決めるファイルと、データをどう変換するかを書くファイルを分けて読むと、構成を追いやすくなります。

4. databricks.ymlを読み解く

バンドルのルートに置くdatabricks.ymlは、一つです。ここからほかのYAMLファイルを読み込めるので、「バンドル内のYAMLは一ファイルだけ」という意味ではありません。

まず押さえたいのは、次の項目です。

例えば、カタログとスキーマを変数にすると、構成は次のように読めます。主要な項目を説明する設定例です。uuidやユーザー名、ワークスペースURLは自分の環境の値に置き換え、実際の生成ファイルにある追加設定は残してください。

bundle:
  name: dabs_practice
  uuid: <your uuid>

include:
  - resources/*.yml

variables:
  catalog:
    description: 出力先のカタログ
  schema:
    description: 出力先のスキーマ

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://<your-workspace-host>
    variables:
      catalog: workspace
      schema: ${workspace.current_user.short_name}
  prod:
    mode: production
    workspace:
      host: https://<your-workspace-host>
    variables:
      catalog: workspace
      schema: prod
    permissions:
      - user_name: <your-user-name>
        level: CAN_MANAGE

includeは、指定したパターンに一致するリソース定義を読み込みます。variablesで定義した値は、ほかの設定から${var.catalog}や${var.schema}として参照できます。パイプライン側にカタログ名が直接書かれている場合は、変数を変更するだけでは出力先は切り替わりません。参照する側も確認する必要があります。

default: trueはターゲットを省略したときの選択先、mode: developmentは開発モードの動作を指定するものです。詳しい構文はバンドル設定の公式ドキュメントを参照してください。

5. devとprodは「設定の切り替え先」

テンプレートには、devとprodのターゲットが用意されます。ただし、prodという名前があるだけで、本番環境が分離されるわけではありません。

ターゲットは、デプロイ時に使う設定のまとまりです。何を分けるかは、その中に書いたワークスペース、カタログ、スキーマ、権限などで決まります。

今回はdevだけを操作します。prodは設定を読み、本番用の値や権限を検討する対象とします。

開発モードでは、リソース名への開発用プレフィックス付与や、スケジュール・トリガーの一時停止などが既定の動作になります。個別設定で上書きできるため、実際に自動実行が止まっているかも確認します。デプロイモードの説明に詳細があります。

また、ワークスペースのバンドルエディターから、別のワークスペースへデプロイすることはサポートされていません。別ワークスペースへ展開する場合は、Gitで共有したコードをCLIやCI/CDからデプロイする構成に進みます。UIでターゲットを選ぶ操作と、環境をまたぐデプロイは分けて考える必要があります。公式の制約を確認してください。

6. devへのデプロイを確認する

初回作成時にデプロイまで完了していれば、まずその結果を確認します。設定を編集した場合や、まだデプロイしていない場合は、次の操作で反映します。

1. バンドル内のdatabricks.ymlを開きます。
2. Deploymentsパネルで、ターゲットにdevを選びます。
3. Deployを押し、設定の検証結果を確認します。
4. 作成・更新されるリソースと出力先を確認して、デプロイを実行します。
5. Project outputの完了状態と、Bundle resourcesにジョブやパイプラインが表示されることを確認します。

ここで確認するのは、定義したリソースが配置されたことです。デプロイ成功と、データ処理の成功は別です。デプロイと実行の公式手順でも、別の操作として説明されています。

サンプルの動作まで確かめる場合は、srcの処理内容と出力先を読んでから、Bundle resourcesのジョブにある実行ボタンを押します。ジョブがパイプラインを起動する構成なら、その更新履歴と作成されたテーブル・ビューまで確認します。デプロイの検証だけでは、入力データや実行時の権限、処理結果の正しさまでは保証されません。

なお、UIから開発ターゲットへデプロイすると、既定ではワークスペース内のソースファイルを直接参照する仕組みが使われます。CLIでデプロイしたときのコピー先だけを探すと戸惑うため、実際のリソースが参照するパスを確認します。YAMLのリソース設定を変更した場合は、再デプロイして反映します。

実際のデプロイ出力では、パイプラインとジョブが各1件作成され、devターゲットの処理が正常終了しました。ここではジョブやパイプラインの実行結果までは確認していません。

Gitへの保存とデプロイは別の操作

バンドルをGitフォルダーに作った段階では、変更がGitHubへ保存されたとは限りません。設定を確認したらGitの差分を見て、必要なファイルをコミット・プッシュします。

デプロイはDatabricksのリソースへ設定を反映する操作、コミット・プッシュは変更履歴をGitへ保存・共有する操作です。片方を済ませたからといって、もう片方まで自動で完了するわけではありません。

同じバンドルから継続してデプロイする場合、既存リソースとの対応はデプロイ状態で管理されます。ジョブの表示名が同じだから自動で関連付くわけではなく、既存ジョブのYAMLをコピーしただけでそのジョブを引き継げるわけでもありません。初回は新規の検証用プロジェクトで、この対応関係を確認するのが分かりやすいです。bundleコマンドの説明に、ターゲットとリソースの識別について記載されています。

つまずいたときに確認すること

次に試したいこと

最初の実践では、databricks.yml、resources、srcがそれぞれ何を担当しているかを押さえると、バンドルの中身を整理しやすくなります。

そのうえで、以前作ったLakeflow SDPの処理を組み込み、保存先を変数にしてみたいです。SQLの変更とパイプラインの設定変更を同じGitの差分で確認できれば、環境へ反映する前のレビューにも役立ちそうです。

さらに先では、CLIからのデプロイやCI/CDにも進めます。まずは画面から作成したバンドルで、コード、リソース定義、デプロイ先のつながりを確認します。

参考資料

• What are Declarative Automation Bundles? — Databricks公式ドキュメント
• Collaborate on bundles in the workspace
• Tutorial: Create and deploy a bundle in the workspace
• Declarative Automation Bundles configuration
• Develop pipelines with Declarative Automation Bundles