このガイドでは、dbt + BigQueryの全設定項目検証を最初から再現するための手順を説明します。
📋 目次
- 環境準備
- プロジェクトセットアップ
- Category 1: プロジェクト基本設定
- Category 2: BigQuery接続設定
- Category 3: モデル設定
- Category 4: テスト設定
- Category 5: ドキュメント設定
- Category 6: パフォーマンス最適化
- Category 7: スナップショット設定
- Category 8: シード設定
- Category 9: フック設定
- Category 10: その他の設定
- ログとテーブルの確認
- トラブルシューティング
1. 環境準備
1.1 前提条件
- OS: macOS / Linux / Windows(WSL推奨)
- Python: 3.8以上
- GCPプロジェクト: BigQueryが有効化されていること
- 権限: BigQuery Data Editor + BigQuery Job User
1.2 ソフトウェアのインストール
# Python仮想環境の作成
python3 -m venv .venv
source .venv/bin/activate # Windowsの場合: .venv\Scripts\activate
# dbt-bigqueryのインストール
pip install dbt-bigquery==1.11.0
# バージョン確認
dbt --version
# 出力例:
# Core:
# - installed: 1.11.5
# - latest: 1.11.5 - Up to date!
# Plugins:
# - bigquery: 1.11.0 - Up to date!1.3 Google Cloud認証
方法1: OAuth認証(ローカル開発推奨)
# gcloud CLIのインストール(未インストールの場合)
# https://cloud.google.com/sdk/docs/install
# 認証
gcloud auth application-default login
# プロジェクトの設定
gcloud config set project your-gcp-project-id方法2: サービスアカウント認証(本番推奨)
# サービスアカウントキーのダウンロード
# GCPコンソール > IAM > Service Accounts > Create Service Account
# - 権限: BigQuery Data Editor, BigQuery Job User
# - JSONキーを作成してダウンロード
# 環境変数に設定
export DBT_BIGQUERY_KEYFILE_JSON='{"type": "service_account", ...}'
# または、ファイルパスを設定
export DBT_BIGQUERY_KEYFILE=/path/to/your-sa-key.json2. プロジェクトセットアップ
2.1 プロジェクトディレクトリ構造
# プロジェクトディレクトリに移動
cd /path/to/jaffle_shop_duckdb
# ディレクトリ構造の確認
tree -L 2
# 出力例:
# .
# ├── dbt_project.yml
# ├── profiles.yml
# ├── models/
# ├── tests/
# ├── seeds/
# ├── snapshots/
# ├── macros/
# └── docs/2.2 profiles.ymlの設定
ローカル開発用(OAuth認証):
# profiles.yml
dbt:
outputs:
sandbox:
type: bigquery
method: oauth
project: your-gcp-project-id
dataset: dbt_sandbox
location: asia-northeast1
threads: 4
priority: interactive
job_execution_timeout_seconds: 600
job_retries: 1
target: sandbox本番用(サービスアカウント認証):
dbt:
outputs:
prod:
type: bigquery
method: service-account-json
project: your-gcp-project-id
dataset: dbt_prod
location: asia-northeast1
threads: 16
priority: batch
job_execution_timeout_seconds: 3600
job_retries: 1
keyfile_json: "{{ env_var('DBT_BIGQUERY_KEYFILE_JSON') }}"
target: prod2.3 接続確認
# dbt debug で接続テスト
dbt debug --profiles-dir . --target sandbox
# 期待される出力:
# Configuration:
# profiles.yml file [OK found and valid]
# dbt_project.yml file [OK found and valid]
#
# Required dependencies:
# - git [OK found]
#
# Connection:
# method: oauth
# database: your-gcp-project-id
# schema: dbt_sandbox
# location: asia-northeast1
# priority: interactive
# Connection test: [OK connection ok]3. Category 1: プロジェクト基本設定
3.1 dbt_project.ymlの検証
# dbt compileでYAMLの構文チェック
dbt compile --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 Running with dbt=1.11.5
# 17:30:01 Found 10 models, 15 tests, 3 seeds
# 17:30:02 Concurrency: 4 threads (target='sandbox')
# 17:30:05 Completed successfully3.2 検証項目
以下の設定項目を検証します:
name: プロジェクト名config-version: 2(必須)version: プロジェクトバージョンprofile: profiles.ymlとの連携model-paths: モデルの配置場所(デフォルト:['models'])seed-paths: シードの配置場所(デフォルト:['seeds'])test-paths: テストの配置場所(デフォルト:['tests'])macro-paths: マクロの配置場所(デフォルト:['macros'])snapshot-paths: スナップショットの配置場所(デフォルト:['snapshots'])target-path: コンパイル出力先(デフォルト:'target')clean-targets:dbt cleanの対象(デフォルト:['target', 'dbt_packages'])require-dbt-version: dbtバージョン制約query-comment: SQLコメント挿入vars: グローバル変数
詳細: Category 1レポート
4. Category 2: BigQuery接続設定
4.1 認証方法の検証
OAuth認証の確認:
# OAuth認証で接続
dbt run --select stg_customers --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 Running with dbt=1.11.5
# 17:30:01 Found 1 model, 0 tests, 0 seeds
# 17:30:02 Concurrency: 4 threads (target='sandbox')
# 17:30:03 1 of 1 START sql view model dbt_sandbox.stg_customers ................... [RUN]
# 17:30:05 1 of 1 OK created sql view model dbt_sandbox.stg_customers .............. [CREATE VIEW in 2.0s]4.2 オプション設定の検証
以下の設定を検証します:
priority: interactive / batchjob_execution_timeout_seconds: タイムアウト時間job_retries: リトライ回数location: データロケーション(asia-northeast1等)maximum_bytes_billed: コスト上限threads: 並列実行数
詳細: Category 2レポート
5. Category 3: モデル設定
5.1 データ準備
# Step 1: シードのロード
dbt seed --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 1 of 3 START seed file dbt_sandbox.raw_customers ........................ [RUN]
# 17:30:02 1 of 3 OK loaded seed file dbt_sandbox.raw_customers ..................... [INSERT 100 in 2.0s]
# 17:30:02 2 of 3 START seed file dbt_sandbox.raw_orders ............................ [RUN]
# 17:30:04 2 of 3 OK loaded seed file dbt_sandbox.raw_orders ........................ [INSERT 99 in 2.0s]
# 17:30:04 3 of 3 START seed file dbt_sandbox.raw_payments .......................... [RUN]
# 17:30:06 3 of 3 OK loaded seed file dbt_sandbox.raw_payments ...................... [INSERT 113 in 2.0s]
# Step 2: Stagingモデルのビルド
dbt run --select staging --profiles-dir . --target sandbox
# 出力例:
# 17:30:10 1 of 3 START sql view model dbt_sandbox.stg_customers .................... [RUN]
# 17:30:12 1 of 3 OK created sql view model dbt_sandbox.stg_customers ............... [CREATE VIEW in 2.0s]
# 17:30:12 2 of 3 START sql view model dbt_sandbox.stg_orders ....................... [RUN]
# 17:30:14 2 of 3 OK created sql view model dbt_sandbox.stg_orders .................. [CREATE VIEW in 2.0s]
# 17:30:14 3 of 3 START sql view model dbt_sandbox.stg_payments ..................... [RUN]
# 17:30:16 3 of 3 OK created sql view model dbt_sandbox.stg_payments ................ [CREATE VIEW in 2.0s]
# Step 3: Martsモデルのビルド
dbt run --select customers orders --profiles-dir . --target sandbox
# 出力例:
# 17:30:20 1 of 2 START sql table model dbt_sandbox.customers ....................... [RUN]
# 17:30:25 1 of 2 OK created sql table model dbt_sandbox.customers .................. [CREATE TABLE (100 rows) in 5.0s]
# 17:30:25 2 of 2 START sql table model dbt_sandbox.orders .......................... [RUN]
# 17:30:30 2 of 2 OK created sql table model dbt_sandbox.orders ..................... [CREATE TABLE (99 rows) in 5.0s]5.2 検証モデルの実行
19個の検証モデルを実行します:
# マテリアライゼーションの検証(5種類)
dbt run --select mat_table_demo --profiles-dir . --target sandbox
dbt run --select mat_view_demo --profiles-dir . --target sandbox
dbt run --select mat_incremental_demo --profiles-dir . --target sandbox
dbt run --select mat_ephemeral_demo --profiles-dir . --target sandbox
dbt run --select mat_matview_demo --profiles-dir . --target sandbox
# パーティショニングの検証(6種類)
dbt run --select partition_date_demo --profiles-dir . --target sandbox
dbt run --select partition_timestamp_demo --profiles-dir . --target sandbox
dbt run --select partition_int_demo --profiles-dir . --target sandbox
dbt run --select partition_filter_required_demo --profiles-dir . --target sandbox
dbt run --select partition_expiration_demo --profiles-dir . --target sandbox
# クラスタリングの検証(3種類)
dbt run --select cluster_single_demo --profiles-dir . --target sandbox
dbt run --select cluster_multi_demo --profiles-dir . --target sandbox
dbt run --select cluster_part_demo --profiles-dir . --target sandbox
# 増分戦略の検証(3種類)
dbt run --select incr_merge_demo --profiles-dir . --target sandbox
dbt run --select incr_insert_overwrite_demo --profiles-dir . --target sandbox
dbt run --select incr_microbatch_demo --profiles-dir . --target sandbox
# その他の設定(2種類)
dbt run --select labels_demo --profiles-dir . --target sandbox
dbt run --select expiration_demo --profiles-dir . --target sandbox詳細: Category 3レポート
6. Category 4: テスト設定
6.1 Schema Testsの実行
# すべてのSchema Testsを実行
dbt test --select test_type:generic --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 1 of 8 START test unique_stg_customers_customer_id ....................... [RUN]
# 17:30:02 1 of 8 PASS unique_stg_customers_customer_id ............................. [PASS in 2.0s]
# 17:30:02 2 of 8 START test not_null_stg_customers_customer_id ..................... [RUN]
# 17:30:04 2 of 8 PASS not_null_stg_customers_customer_id ........................... [PASS in 2.0s]
# ...
# 17:30:20 Completed successfully6.2 Singular Testsの実行
# Singular Testsを実行
dbt test --select test_type:singular --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 1 of 2 START test assert_positive_order_amount ........................... [RUN]
# 17:30:02 1 of 2 PASS assert_positive_order_amount ................................. [PASS in 2.0s]
# 17:30:02 2 of 2 START test assert_valid_order_status_transition ................... [RUN]
# 17:30:04 2 of 2 PASS assert_valid_order_status_transition ......................... [PASS in 2.0s]6.3 Unit Testsの実行
# Unit Testsを実行(高速)
dbt test --select test_type:unit --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 1 of 10 START unit test customers::test_customer_aggregation ............. [RUN]
# 17:30:01 1 of 10 PASS unit test customers::test_customer_aggregation .............. [PASS in 1.0s]
# ...
# 17:30:15 Completed successfully詳細: Category 4レポート
7. Category 5: ドキュメント設定
7.1 dbt docsの生成
# ドキュメント生成
dbt docs generate --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 Running with dbt=1.11.5
# 17:30:01 Found 10 models, 15 tests, 3 seeds
# 17:30:05 Building catalog
# 17:30:10 Catalog written to target/catalog.json
# 17:30:10 Manifest written to target/manifest.json7.2 dbt docsの表示
# ローカルサーバーを起動
dbt docs serve --profiles-dir . --port 8080
# ブラウザで開く
open http://localhost:8080詳細: Category 5レポート
8. Category 6: パフォーマンス最適化
6.1 スロット使用状況の確認
# BigQuery CLIでスロット使用状況を確認
bq ls -j -a -n 50 your-gcp-project-id
# dbt実行中のスロット監視
dbt run --select customers --profiles-dir . --target sandbox &
bq show -j $(bq ls -j -a -n 1 your-gcp-project-id | tail -n 1 | awk '{print $1}')6.2 クエリパフォーマンスの測定
# --log-level debug でクエリ詳細を確認
dbt run --select customers --profiles-dir . --target sandbox --log-level debug
# 出力例(抜粋):
# DEBUG: Executing SQL: CREATE TABLE `your-gcp-project-id.dbt_sandbox.customers` AS ...
# DEBUG: BigQuery adapter: Query complete, processed 5.2 MB in 3.2s詳細: Category 6レポート
9. Category 7: スナップショット設定
9.1 スナップショットの作成
# 初回スナップショット
dbt snapshot --profiles-dir . --target sandbox
# 出力例:
# 17:30:00 1 of 1 START snapshot dbt_sandbox_snapshots.customers_snapshot .......... [RUN]
# 17:30:05 1 of 1 OK snapshotted dbt_sandbox_snapshots.customers_snapshot ........... [INSERT 100 in 5.0s]9.2 データ変更後の再スナップショット
# データを変更(例: raw_customersを更新)
# その後、再度スナップショット実行
dbt snapshot --profiles-dir . --target sandbox
# 出力例:
# 17:35:00 1 of 1 START snapshot dbt_sandbox_snapshots.customers_snapshot .......... [RUN]
# 17:35:05 1 of 1 OK snapshotted dbt_sandbox_snapshots.customers_snapshot ........... [MERGE (5 inserted, 3 updated) in 5.0s]詳細: Category 7レポート
10. Category 8: シード設定
10.1 シードのロード(各種設定)
# 基本的なシードロード
dbt seed --profiles-dir . --target sandbox
# 特定のシードのみロード
dbt seed --select raw_customers --profiles-dir . --target sandbox
# full-refreshでの再ロード
dbt seed --full-refresh --profiles-dir . --target sandbox詳細: Category 8レポート
11. Category 9: フック設定
11.1 フックの実行確認
# フック付きでdbt run実行
dbt run --profiles-dir . --target sandbox
# 出力例(on-run-startフックが実行される):
# 17:30:00 Running with dbt=1.11.5
# 17:30:01 1 of 1 START hook: dbt.on-run-start.0 .................................... [RUN]
# 17:30:02 1 of 1 OK hook: dbt.on-run-start.0 ....................................... [OK in 1.0s]
# 17:30:02 1 of 10 START sql view model dbt_sandbox.stg_customers ................... [RUN]
# ...
# 17:30:50 1 of 1 START hook: dbt.on-run-end.0 ...................................... [RUN]
# 17:30:51 1 of 1 OK hook: dbt.on-run-end.0 ......................................... [OK in 1.0s]詳細: Category 9レポート
12. Category 10: その他の設定
12.1 varsの利用
# コマンドラインからvarsを渡す
dbt run --select customers --vars '{"fiscal_year_start_month": 4}' --profiles-dir . --target sandbox12.2 dbtパッケージのインストール
# packages.ymlに定義したパッケージをインストール
dbt deps
# 出力例:
# 17:30:00 Installing dbt-labs/dbt_utils
# 17:30:05 Installed from version 1.1.1
# 17:30:05 Up to date!詳細: Category 10レポート
13. ログとテーブルの確認
13.1 dbt実行ログの保存
# ログをファイルに保存
mkdir -p logs/verification
# すべてのカテゴリを実行してログ保存
dbt seed --profiles-dir . --target sandbox 2>&1 | tee logs/verification/01_seed.log
dbt run --profiles-dir . --target sandbox 2>&1 | tee logs/verification/02_run.log
dbt test --profiles-dir . --target sandbox 2>&1 | tee logs/verification/03_test.log
dbt snapshot --profiles-dir . --target sandbox 2>&1 | tee logs/verification/04_snapshot.log13.2 BigQueryテーブル情報の取得
# テーブル一覧
bq ls your-gcp-project-id:dbt_sandbox
# 特定テーブルのスキーマ確認
bq show --schema --format=prettyjson your-gcp-project-id:dbt_sandbox.customers
# テーブルの統計情報
bq show your-gcp-project-id:dbt_sandbox.customers
# 出力例:
# Last modified Schema Total Rows Total Bytes Expiration Time Partitioning Clustered Fields Labels
# ----------------- ------------------------------------ ------------ ------------- ------------ ------------------- ------------------ --------
# 17 Feb 00:30:00 |- customer_id: integer 100 5242880 DAY (field: order_ verification:model
# |- first_name: string _date) customer_id,
# |- last_name: string status
# |- first_order: date
# |- most_recent_order: date
# |- number_of_orders: integer
# |- customer_lifetime_value: float
# テーブルのサンプルデータ確認
bq query --use_legacy_sql=false 'SELECT * FROM `your-gcp-project-id.dbt_sandbox.customers` LIMIT 5'13.3 コンパイル済みSQLの確認
# コンパイル済みSQLの場所
ls -lh target/compiled/jaffle_shop/models/
# 特定モデルのコンパイル済みSQLを確認
cat target/compiled/jaffle_shop/models/customers.sql
# テストのコンパイル済みSQL
cat target/compiled/jaffle_shop/models/staging/schema.yml/unique_stg_customers_customer_id.sql14. トラブルシューティング
14.1 認証エラー
エラー: Could not find Application Default Credentials
解決策:
# OAuth認証を再実行
gcloud auth application-default login
# または、サービスアカウントキーを設定
export DBT_BIGQUERY_KEYFILE_JSON='...'14.2 接続エラー
エラー: Database Error: 403 Access Denied
解決策:
# 権限を確認
gcloud projects get-iam-policy your-gcp-project-id
# 必要な権限を付与
gcloud projects add-iam-policy-binding your-gcp-project-id \
--member="user:your-email@example.com" \
--role="roles/bigquery.dataEditor"
gcloud projects add-iam-policy-binding your-gcp-project-id \
--member="user:your-email@example.com" \
--role="roles/bigquery.jobUser"14.3 テスト失敗
エラー: FAIL 5 unique_stg_orders_order_id
解決策:
# 失敗したテストのコンパイル済みSQLを確認
cat target/compiled/jaffle_shop/models/staging/schema.yml/unique_stg_orders_order_id.sql
# BigQueryで直接実行して詳細を確認
bq query --use_legacy_sql=false < target/compiled/jaffle_shop/models/staging/schema.yml/unique_stg_orders_order_id.sql
# データを確認
bq query --use_legacy_sql=false 'SELECT order_id, COUNT(*) as cnt FROM `your-gcp-project-id.dbt_sandbox.stg_orders` GROUP BY order_id HAVING cnt > 1'14.4 パフォーマンス問題
症状: dbt run が10分以上かかる
解決策:
# threadsを増やす
dbt run --threads 8 --profiles-dir . --target sandbox
# 特定のモデルのみ実行
dbt run --select +customers --profiles-dir . --target sandbox
# --log-level debug で詳細確認
dbt run --select customers --log-level debug --profiles-dir . --target sandbox15. 完全な実行シーケンス(全カテゴリ)
以下は、すべてのカテゴリを順番に実行するスクリプトです。
#!/bin/bash
set -e
# プロジェクトディレクトリに移動
cd /path/to/jaffle_shop_duckdb
# ログディレクトリ作成
mkdir -p logs/verification
echo "=== Category 1: プロジェクト基本設定 ==="
dbt compile --profiles-dir . --target sandbox 2>&1 | tee logs/verification/01_compile.log
echo "=== Category 2: BigQuery接続設定 ==="
dbt debug --profiles-dir . --target sandbox 2>&1 | tee logs/verification/02_debug.log
echo "=== Category 3: モデル設定 ==="
dbt seed --profiles-dir . --target sandbox 2>&1 | tee logs/verification/03_seed.log
dbt run --select staging --profiles-dir . --target sandbox 2>&1 | tee logs/verification/04_staging.log
dbt run --select customers orders --profiles-dir . --target sandbox 2>&1 | tee logs/verification/05_marts.log
dbt run --select verification --profiles-dir . --target sandbox 2>&1 | tee logs/verification/06_verification_models.log
echo "=== Category 4: テスト設定 ==="
dbt test --select test_type:generic --profiles-dir . --target sandbox 2>&1 | tee logs/verification/07_schema_tests.log
dbt test --select test_type:singular --profiles-dir . --target sandbox 2>&1 | tee logs/verification/08_singular_tests.log
dbt test --select test_type:unit --profiles-dir . --target sandbox 2>&1 | tee logs/verification/09_unit_tests.log
echo "=== Category 5: ドキュメント設定 ==="
dbt docs generate --profiles-dir . --target sandbox 2>&1 | tee logs/verification/10_docs_generate.log
echo "=== Category 6: パフォーマンス最適化 ==="
# パフォーマンス測定(ログに時間が記録される)
time dbt run --select customers --profiles-dir . --target sandbox 2>&1 | tee logs/verification/11_performance.log
echo "=== Category 7: スナップショット設定 ==="
dbt snapshot --profiles-dir . --target sandbox 2>&1 | tee logs/verification/12_snapshot.log
echo "=== Category 8: シード設定 ==="
# 既に実行済み(Category 3で実施)
echo "=== Category 9: フック設定 ==="
# フック付きrun(ログにフック実行が記録される)
dbt run --select stg_customers --profiles-dir . --target sandbox 2>&1 | tee logs/verification/13_hooks.log
echo "=== Category 10: その他の設定 ==="
dbt deps 2>&1 | tee logs/verification/14_deps.log
echo "=== BigQueryテーブル情報取得 ==="
bq ls your-gcp-project-id:dbt_sandbox > logs/verification/15_table_list.txt
bq show your-gcp-project-id:dbt_sandbox.customers > logs/verification/16_customers_table_info.txt
echo "=== 完了 ==="
echo "ログは logs/verification/ に保存されました"実行方法:
# 実行権限を付与
chmod +x run_all_verification.sh
# 実行
./run_all_verification.sh16. 検証結果の確認
16.1 成功基準
すべてのカテゴリで以下が確認できればOK:
- Category 1:
dbt compileが成功 - Category 2:
dbt debugで Connection test: OK - Category 3: 19個の検証モデルがすべてビルド成功
- Category 4: すべてのテストがPASS
- Category 5:
dbt docs generateが成功 - Category 6: パフォーマンス測定完了
- Category 7: スナップショット実行成功
- Category 8: シードロード成功(100 + 99 + 113行)
- Category 9: フック実行確認
- Category 10: dbtパッケージインストール成功
16.2 ログの確認
# すべてのログファイルでERRORを検索
grep -i "error" logs/verification/*.log
# FAILしたテストを検索
grep -i "fail" logs/verification/*.log
# エラーがなければ何も出力されない17. まとめ
この再実行ガイドに従えば、dbt + BigQueryの全設定項目検証を再現できます。
推奨実行時間: 約3〜4時間(すべてのカテゴリ)
ポイント:
- 各カテゴリを順番に実行
- ログをすべて保存
- BigQueryテーブル情報も保存
- エラーが出たらトラブルシューティングを参照
次のステップ:
- プロジェクト概要で全体像を把握
- 各カテゴリの詳細レポートで深掘り
- ベストプラクティスを自プロジェクトに適用
最終更新: 2026-02-17 バージョン: 1.0 作成者: dbt検証プロジェクトチーム