0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@sato1046

dbt初心者が環境構築でつまずいた3つのポイントと解決法【BigQuery + Windows 11編】

0
Last updated at Posted at 2026-01-15

はじめに

「このSQL、誰がメンテナンスするんだろう...」

300行のSQL。スクロールしても終わりが見えません。変更を加えようとすると、どこに影響が出るのか分かりません。Treasure Dataでテストを実施し、Excelで定義書を管理しています。しかし、SQL変更のたびに定義書を手動更新し、テスト項目書との整合性を目視確認する必要があります。この作業に、毎回半日かかります。

「もっと効率的な方法があるはずだ」

転職活動を見据えて、私は決断しました。10日間でdbtをマスターし、この300行のSQLを現代的なデータパイプラインに作り変えます。

しかし、いざdbtの学習を始めてみると、環境構築の段階で予想外のつまずきポイントがありました。「dbtは簡単に始められる」という情報を見かけることが多かったのですが、公式ドキュメントだけでは分からない細かい罠がいくつも...

この記事では、10日間のdbt学習の最初のステップ「環境構築」で実際につまずいた3つのポイントと、その解決方法を共有します。Windows 11環境でdbtを始める方の参考になれば幸いです。

私の状況：

  • データエンジニア歴：2年以上
  • 技術スタック：SQL 6年、Python 3年、BigQuery、GCP
  • 課題：300行の実務SQLが保守不可能
  • 目標：10日でdbtをマスターし、転職活動のポートフォリオを作成
  • 環境：Windows 11、Command Prompt、Python公式インストーラー

この記事で分かること：

  • Windows 11でのdbt環境構築の手順
  • PATHの恒久設定方法（システム環境変数）
  • JSONキーファイル名の罠
  • BigQueryデータセットのロケーション設定
  • profiles.ymlの書き方

環境

  • OS: Windows 11
  • シェル: Command Prompt（コマンドプロンプト）
  • Python: 3.8以上（公式インストーラーからインストール）
  • dbt-bigquery: 1.10.2
  • データウェアハウス: BigQuery
  • ロケーション: asia-northeast1（東京）

つまずいたポイント1: PATHの恒久設定

何につまずいたか

pip install dbt-bigqueryでインストールが成功したのに、新しいコマンドプロンプトを開くとdbtコマンドが認識されない...

C:\Users\YourName> dbt --version
'dbt' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

インストール直後のコマンドプロンプトでは動いたのに、閉じて開き直すと動かなくなる...何か設定が足りないはずと悩みました。

解決方法

Windows 11では、システム環境変数のPathに永続的な設定を追加する必要があります。

1. Pythonのインストール場所を確認

まず、Pythonがどこにインストールされているか確認します。

where python

出力例：

C:\Users\YourName\AppData\Local\Programs\Python\Python311\python.exe

この場合、Scriptsフォルダは以下の場所にあります：

C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts

2. システム環境変数を設定

  1. スタートメニューを右クリック → システムを選択
  2. システムの詳細設定をクリック
  3. 環境変数ボタンをクリック
  4. システム環境変数のPathを選択 → 編集をクリック
  5. 新規をクリックして以下を追加：
C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts

重要: YourNameとPython311の部分は、ステップ1で確認した実際のパスに合わせてください。

  1. OKを3回押して全てのダイアログを閉じる

3. コマンドプロンプトを再起動

既存のコマンドプロンプトは環境変数の変更を認識しないため、必ず閉じて新しく開き直してください。

4. 確認

dbt --version

これで、どのディレクトリからでもdbtコマンドが使えるようになります。

学んだこと

  • pip installだけでは、コマンドのPATHは永続化されない
  • Windows環境ではシステム環境変数の設定が必要
  • コマンドプロンプトは再起動しないと環境変数の変更が反映されない

つまずいたポイント2: JSONキーファイル名の二重拡張子

何につまずいたか

BigQueryのサービスアカウントキーをダウンロードして、profiles.ymlにパスを設定したのに、以下のエラーが出ました。

Error: [Errno 2] No such file or directory: 'C:/Users/YourName/.dbt/keys/your-key.json'

ファイルは確かに存在するのに、なぜ認識されないのか...

解決方法

原因は、ファイル名が.json.jsonの二重拡張子になっていたことでした。

確認方法

Windowsのエクスプローラーでは、デフォルトで拡張子が非表示になっているため、実際のファイル名がyour-key.json.jsonでも、表示上はyour-key.jsonに見えてしまいます。

エクスプローラーで拡張子を表示する設定：

  1. エクスプローラーを開く
  2. 上部メニューの表示タブをクリック
  3. 表示→ファイル名拡張子にチェックを入れる

これで実際のファイル名が表示されます。

もしyour-key.json.jsonになっていたら、ファイル名を変更します：

  1. ファイルを右クリック → 名前の変更
  2. .jsonの部分を削除（末尾の.jsonを1つ削除）
  3. 最終的にyour-key.jsonになればOK

コマンドプロンプトで確認する方法

cd C:\Users\YourName\.dbt\keys
dir

出力例：

2025/11/05  14:30    2,345 your-key.json.json  ← これが問題！

ファイル名変更（コマンドプロンプト）

cd C:\Users\YourName\.dbt\keys
ren your-key.json.json your-key.json

profiles.ymlでのパス指定（Windows）

Windowsの場合、パスの指定方法に注意が必要です。

C:\Users\YourName.dbt\profiles.yml
dbt_learning:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: service-account
      project: your-gcp-project-id
      dataset: dbt_learning
      threads: 1
      location: asia-northeast1
      # Windowsの場合、以下のいずれかの書き方でOK
      keyfile: C:/Users/YourName/.dbt/keys/your-key.json  # スラッシュ
      # または
      keyfile: C:\Users\YourName\.dbt\keys\your-key.json  # バックスラッシュ

おすすめ: スラッシュ/の方がエラーが起きにくいです。

学んだこと

  • Windowsエクスプローラーはデフォルトで拡張子を隠す
  • dirコマンドで実際のファイル名を確認すべき
  • profiles.ymlでのパス指定は/（スラッシュ）推奨

つまずいたポイント3: BigQueryデータセットのロケーション設定

何につまずいたか

dbtプロジェクトを作成して、最初のモデルを実行したときに以下のエラーが出ました。

Error: Not found: Dataset dbt_learning was not found in location US

profiles.ymlでlocation: asia-northeast1を指定しているのに、なぜUSで探すのか...

原因

profiles.ymlでロケーションを指定しても、BigQuery側にデータセットが存在しないと、デフォルトのUSロケーションで検索されるという仕様でした。

つまり、dbtがデータセットを自動作成してくれるわけではなく、事前にBigQueryコンソールで正しいロケーションにデータセットを作成する必要があります。

解決方法

1. BigQueryコンソールでデータセットを作成

  1. BigQueryコンソールをブラウザで開く
  2. プロジェクトを選択
  3. 「データセットを作成」をクリック
  4. データセットID: dbt_learning（profiles.ymlと一致させる）
  5. データのロケーション: asia-northeast1 (Tokyo)を選択 ← 重要！
  6. 「データセットを作成」をクリック

2. profiles.ymlの設定を確認

C:\Users\YourName.dbt\profiles.yml
dbt_learning:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: service-account
      project: your-gcp-project-id
      dataset: dbt_learning  # 上で作成したデータセット名
      threads: 1
      location: asia-northeast1  # データセットのロケーションと一致
      keyfile: C:/Users/YourName/.dbt/keys/your-key.json

3. 接続テスト

cd C:\path\to\your\dbt_project
dbt debug

全てのチェックがOKになれば成功です。

All checks passed!

学んだこと

  • dbtはデータセットを自動作成しない
  • profiles.ymlのlocation設定と、BigQuery上のデータセットのロケーションを一致させる必要がある
  • 日本からアクセスする場合、asia-northeast1（東京リージョン）が推奨
  • dbt debugコマンドで接続確認できる

おまけ: プロファイル設定のミス（Day 3-4でつまずいた）

環境構築が完了した後、Day 3-4でさらにつまずいたポイントがあったので、おまけとして追加します。

何につまずいたか

新しいプロジェクトを作成してdbt runを実行したときに、以下のエラーが出ました。

Error: Could not find profile named 'dbt_learning'

原因

dbt initで新しいプロジェクトを作成したときに、プロジェクト名を入力しますが、この名前がdbt_project.ymlのprofileに設定されます。この名前とprofiles.ymlのプロファイル名が一致していないとエラーになります。

解決方法

1. dbt_project.ymlを確認

dbt_project.yml
name: 'my_new_project'
version: '1.0.0'
config-version: 2

profile: 'dbt_learning'  # ← この名前を確認

2. profiles.ymlのプロファイル名を確認

C:\Users\YourName.dbt\profiles.yml
dbt_learning:  # ← dbt_project.ymlのprofileと一致させる
  target: dev
  outputs:
    dev:
      type: bigquery
      # ...

名前が一致していればOKです。不一致の場合は、どちらかを修正してください。

学んだこと

  • dbt_project.ymlのprofileとprofiles.ymlのプロファイル名は一致させる必要がある
  • プロジェクト名（name）とプロファイル名（profile）は別物
  • 複数プロジェクトを管理する場合、プロファイルを共通化できる

Windows特有の注意点

ディレクトリパスの指定

Windows環境では、ディレクトリの区切り文字に注意が必要です。

# Windowsスタイル（バックスラッシュ）
cd C:\Users\YourName\dbt_learning

# Unixスタイル（スラッシュ）も使える
cd C:/Users/YourName/dbt_learning

profiles.ymlやdbt_project.ymlでは、スラッシュ/を使う方がエラーが起きにくいです。

ホームディレクトリの場所

Windowsでは、.dbtフォルダは以下の場所に作成されます：

C:\Users\YourName\.dbt\

.dbtフォルダが見えない場合：

  1. エクスプローラーで上部メニュー表示タブをクリック
  2. 表示→隠しファイルにチェックを入れる

環境構築後の最初の一歩

環境構築が完了したら、まずは公式が推奨する手順で動作確認してみましょう。

1. テスト用テーブルの作成

BigQueryコンソールで簡単なテーブルを作成します。

CREATE TABLE `your-project-id.dbt_learning.raw_customers` AS
SELECT
  1 AS customer_id,
  'alice@example.com' AS email
UNION ALL
SELECT
  2 AS customer_id,
  'bob@example.com' AS email;

2. ソース定義の作成

models\schema.yml
version: 2

sources:
  - name: raw_data
    database: your-project-id
    schema: dbt_learning
    tables:
      - name: raw_customers

3. 最初のモデルを作成

models\customers.sql
{{ config(materialized='view') }}

SELECT
  customer_id,
  LOWER(email) AS email_lower
FROM {{ source('raw_data', 'raw_customers') }}

4. モデルの実行

cd C:\path\to\your\dbt_project
dbt run

成功すると、BigQueryにcustomersビューが作成されます。

5. ドキュメント生成（オプション）

dbtの強力な機能の一つが、ドキュメント自動生成です。

# ドキュメント生成
dbt docs generate

# ローカルでドキュメントを表示（ブラウザが自動で開きます）
dbt docs serve

ブラウザが開き、プロジェクトのドキュメントが表示されます。モデルの依存関係をLineage Graph（系譜図）として可視化できるのが、dbtの大きな魅力です。

詳しくは、公式ドキュメントのAbout documentationを参照してください。

まとめ

dbtの環境構築（Windows 11）でつまずいた主なポイント：

  1. PATHの恒久設定 → システム環境変数のPathにScriptsフォルダを追加
  2. JSONキーファイル名の二重拡張子 → エクスプローラーで拡張子表示を有効化
  3. BigQueryデータセットのロケーション → 事前にBigQueryコンソールで正しいロケーションに作成
  4. プロファイル設定のミス → dbt_project.ymlとprofiles.ymlの名前を一致

Windows特有の注意点：

  • パス指定は/（スラッシュ）推奨
  • システム環境変数の設定後はコマンドプロンプト再起動必須
  • エクスプローラーで拡張子と隠しファイルを表示する設定を有効化

初期設定さえクリアすれば、dbtは非常に強力なツールです。私の場合、Day 1-2の環境構築に約4時間かかりましたが、Day 3以降はスムーズに学習を進められました。

この環境構築を突破した後の10日間で、私は以下を達成しました：

  • 300行の単一SQLファイル → 12モデルに分解
  • 処理時間96%削減（2時間→6分）
  • 27テストで品質保証
  • ドキュメント自動生成

10日間の学習の全体像については、別記事「実務SQLをdbt化した10日間 - データエンジニアが語る、ビジネス視点を失わない技術習得法」で詳しく解説しています。

これからdbtを始める方の参考になれば幸いです。

参考リンク

注意点

私自身まだdbt学習を始めて10日間のため、より効率的な方法や、現場での実践的な使い方については、まだ知見が浅い部分があります。

もし間違いや改善点がありましたら、コメント欄でご指摘いただけると幸いです。

公開成果物

この環境構築を突破すれば、dbtの世界が開けます。次のステップで、ref()を使ったモデル連携やテストの実装に進んでいきましょう！

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?