dbt Databricks アダプター実践ガイド: Delta Lake との連携を最短で固める

dbt Databricks アダプターは、Delta Lake の ACID/タイムトラベル/MERGE を活かして、データモデリングから本番運用までを単一の開発体験で支えます。本稿は公式ドキュメントの挙動を前提に、試験でも問われやすい安定概念に絞って整理します。

バージョン依存の細部は言及を控え、接続設定、マテリアライゼーション、インクリメンタル戦略、Unity Catalog 権限、運用最適化の順で、受験と現場の双方で迷わない基準を提示します。

dbt × Databricks × Delta Lake の基礎

dbt-databricks は Databricks SQL Warehouse/クラスターに対して SQL を発行し、Delta Lake テーブルに対して view/table/incremental のマテリアライゼーションを実現します。Delta Lake の ACID トランザクションと MERGE が、信頼できるアップサートの土台です。

Analytics Engineer の観点では、インクリメンタル戦略、Unity Catalog の 3 階層名、プロファイル設定（host/http_path/token）の整合が頻出ポイントです。

• Delta Lake は既定で ACID、スキーマ強制/進化、タイムトラベルを提供
• dbt のリレーション名は Databricks では catalog.schema.identifier の 3 階層
• インクリメンタルで MERGE を使うには unique_key の指定が実務でも試験でも定石

dbt から Delta Lake への実行フロー（概念）

インストールの最小例（ローカル開発）

python -m venv .venv
source .venv/bin/activate  # Windows は .venv\\Scripts\\activate
pip install --upgrade pip
pip install dbt-databricks

接続とプロファイル設定（SQL Warehouse / Unity Catalog）

Databricks への接続は profiles.yml に host, http_path, token を定義します。SQL Warehouse を使うと安定した ANSI SQL 実行と自動スケーリングが得られます。Unity Catalog を使う場合は catalog を明示しましょう。legacy の Hive Metastore を使う場合は catalog を hive_metastore にします。

試験・実務ともに http_path の値が SQL Warehouse 用とクラスター用で異なる点、そして catalog と schema の使い分けが落とし穴です。

• host は https:// とワークスペースホストを含める
• http_path は SQL Warehouse の場合 /sql/1.0/warehouses/....
• catalog は Unity Catalog のカタログ名（例: main）か hive_metastore
• threads は上げすぎるとメタストアロックの待ちが増えるため段階調整

profiles.yml の例（SQL Warehouse とクラスター）

databricks_profile:
  target: dev
  outputs:
    dev:
      type: databricks
      method: http
      host: https://<your-workspace-host>
      http_path: /sql/1.0/warehouses/<warehouse-id>
      token: <databricks-personal-access-token>
      catalog: main            # Unity Catalog を利用しないなら hive_metastore
      schema: analytics_dev    # ユーザーごとの開発スキーマを推奨
      threads: 4
    cluster_dev:
      type: databricks
      method: http
      host: https://<your-workspace-host>
      http_path: /sql/protocolv1/o/<org-id>/<cluster-id>   # 全用途クラスター
      token: <databricks-personal-access-token>
      catalog: hive_metastore
      schema: analytics_dev
      threads: 4

マテリアライゼーションと Delta テーブル作成

Databricks アダプターは table/view/incremental/seed/snapshot をサポートします。Delta Lake を明示したい場合は file_format=delta を指定します。デフォルトが Delta である環境もありますが、試験・保守性の観点から明示を推奨します。

テーブルプロパティで自動最適化や圧縮を有効化できます。プロパティ名はワークスペース設定に依存するため、安定性重視なら post-hook で OPTIMIZE を呼ぶ方が安全です。

• table は完全再作成、view は軽量
• incremental は Delta の MERGE/INSERT を活用
• ephemeral は実体を作らず上流にインライン展開
• テーブル名は catalog.schema.identifier の 3 階層で管理

Delta テーブルの基本モデル例

{{ config(
    materialized='table',
    file_format='delta',
    tags=['core'],
    grants={'select': ['analyst_group']}
) }}

with src as (
  select * from {{ source('app', 'orders_raw') }}
)
select
  order_id,
  customer_id,
  cast(order_ts as timestamp) as order_ts,
  amount
from src

インクリメンタル戦略と Delta Lake でのアップサート設計

インクリメンタルは大量データでの再計算コストを抑制します。Databricks アダプターでは、unique_key を指定すると MERGE が選ばれ、アップサートが可能になります。unique_key がない場合は append が無難です。パーティションを張る場合は insert_overwrite を検討します。

CDC の到着遅延や再取り込みに備え、is_incremental 条件で WHERE 句を分けるのが定石です。水位は更新タイムスタンプや増分 ID を用いると安定します。

• unique_key を与えると MERGE を使用でき、更新に強い
• パーティションと相性がよいのは insert_overwrite（再計算対象を限定）
• is_incremental ブロックで到着遅延のバッファを設ける
• 小刻みなトランザクションよりバッチをまとめた方がロック競合が減る

MERGE を使うインクリメンタルモデル（到着遅延に対応）

{{ config(
    materialized='incremental',
    file_format='delta',
    unique_key='order_id',
    incremental_strategy='merge',
    on_schema_change='append_new_columns'  # 追加カラムは自動追加（安定挙動）
) }}

with staged as (
  select
    order_id,
    customer_id,
    cast(order_ts as timestamp) as order_ts,
    amount,
    ingestion_ts
  from {{ ref('stg_orders') }}
  {% if is_incremental() %}
    where order_ts >= date_sub(current_timestamp(), 7)  -- 到着遅延のバッファ
  {% endif %}
)

select * from staged

Unity Catalog、権限、環境分離の実務

Unity Catalog では catalog.schema.table の 3 階層でオブジェクトを管理します。dbt の database は Databricks では catalog に相当します。開発・本番で catalog/schema を明確に分け、ターゲット切替で衝突を防ぎます。

権限は dbt の grants 設定から付与できます。CREATE SCHEMA は pre-hook、統計最適化などは post-hook で呼ぶパターンが安全です。

• profiles.yml の catalog と schema を明示し、target ごとに切替
• 開発はユーザー固有 schema、本番はロックダウンされた schema
• 権限はロール/グループ単位で付与し、直接ユーザー付与は避ける

権限とスキーマ作成のフック例

{{ config(
    materialized='table',
    file_format='delta',
    grants={'select': ['analyst_group'], 'usage': ['bi_group']},
    pre_hook=["create schema if not exists {{ target.catalog }}.{{ target.schema }}"],
    post_hook=["analyze table {{ this }} compute statistics"]
) }}

select 1 as ok

運用と性能最適化: OPTIMIZE・ZORDER・検証

Delta Lake の性能維持にはファイルサイズの最適化と統計の更新が重要です。大規模テーブルは OPTIMIZE、アクセスパターンが明確なら ZORDER を post-hook で実行します。VACUUM は保持期間とガバナンスルールに合わせて慎重に運用します。

ジョブ設計では run-operation でメタ操作を分離し、並列度はメタストア負荷と相談して段階的に上げます。テストは not_null/unique/relationships を最優先に据え、障害時の切り戻しには Delta のタイムトラベルを活用できます。

• OPTIMIZE と ANALYZE を定期ジョブに組み込み、ZORDER は主なフィルタ列で実施
• VACUUM は削除保持期間と監査要件を確認してから設定
• dbt test を CI に組込み、スキーマ進化は小刻みに
• 長時間トランザクションは分割し、ロック待ちを低減

OPTIMIZE/ZORDER の post-hook 例（慎重に適用）

{{ config(
    materialized='incremental',
    file_format='delta',
    unique_key='id',
    incremental_strategy='merge',
    post_hook=[
      "optimize {{ this }} zorder by (customer_id, order_ts)",
      "analyze table {{ this }} compute statistics"
    ]
) }}

select * from {{ ref('stg_fact') }}

問題で確認

よくある質問