dbtガイド

クイックリンク

• プライマリプロジェクト
• dbt docs

概要と目的

dbtはdata build toolの略で、データウェアハウスのデータ変換を管理するためのオープンソースプロジェクトです。データがウェアハウスに読み込まれた後、dbtはアナリティクス推進に必要なすべてのデータ変換を管理できます。また、テストとドキュメントが組み込まれているため、生成・分析しているテーブルに高い信頼性を持つことができます。

dbtとは何かについての概要は以下のリンクが参考になります。

• dbtとは正確に何か？ - ツールを理解するための技術的でない概要
• dbtとは何か？ - ドキュメントから直接得られるやや技術的な説明

なぜdbtを使うのかについては、いくつかの理由があります。

第一に、活発なコミュニティを持つオープンソースツールであることです。オープンソースツールを選ぶことで、大きなデータコミュニティとコラボレーションし、独自のソリューションよりも速く問題を解決できます。

第二に、バージョン管理を念頭に置いて作られていることです。GitLabにとっては、会社の構築と運営にこの製品を使用しているため、これは不可欠です。

第三に、アナリストの言語であるSQLで話せることです。SQLは多くの人の仕事に不可欠になっているため、貢献できる人の数が増えます。

最後に、最初からテストとドキュメントを統合することでチームがより速く動けるようになります。

dbtの基本の詳細については、データアナリストオンボーディングIssueテンプレートを参照してください。

データ変換にdbtパッケージを使用することもあります。パッケージ管理はdbtに組み込まれています。利用可能なパッケージの全リストはdbt Hubサイトにあります。

dbtの実行

dbtを使用する場合は、dbtドキュメントに優れたチュートリアルがあります。JaffleShopというフィクションのビジネスのデータに取り組むセットアップについて説明しています。

dbtを使用してデータチームのプロジェクトに貢献する場合は、Snowflakeインスタンスへのアクセスが必要です。これはアクセスリクエストで行えます。

ローカル環境

GitLabチームメンバーがdbtプロジェクトに貢献するための「ローカル」開発環境を整備するために、makeレシピを使用したユーザー専用の開発データベースと仮想環境を使用します。

「ローカル」ユーザー専用開発データベース

チームメンバーが必要とする場合、_PREPと_PRODサフィックスを持つSnowflakeユーザーに対応するローカル開発データベースを作成します。これらはSnowflakeのPREPとPRODデータベースに対応しています。ローカル環境内で実行した場合、メインのdbtプロジェクトはこれらを対象とするため、貢献者はdbtプロジェクトへの変更を開発・テストできます。dbtプロジェクト内の開発プロセスの詳細はdbt変更ワークフローページを参照してください。

これらの開発データベース内に構築されたデータは、ローカル開発のためにのみ使用されるため、エフェメラルと見なす必要があります。dbtの最適な使用と適切なセキュリティとコンプライアンスを確保するために、これらのデータベースは所有ユーザーが定期的にクリーニングする必要があります。このRunbookを使用してそのプロセスを迅速かつ簡単に行えます。各開発サイクルの終わりまたは始まりに実行することをお勧めします。さらに、データ保持ポリシーと手順への準拠を確保するために、変更なしに80日経過した後、開発環境のすべてのテーブルを自動的に削除します。この保持期間はdbtプロジェクトのdev_db_object_expiration変数で設定され、テーブルは毎週末に削除されます。

注意: 開発データベースは、対応するチームメンバーがSnowflakeへのアクセスが削除されると同時に削除されます（オフボーディングや非アクティブな使用の場合）。開発データベースのバックアッププロセスはありません。

設定

• Snowflakeインスタンスと自分のSnowflakeユーザー用の専用開発データベースへのアクセスがあることを確認します
• Makeがインストールされていることを確認します（新しいMacとXCodeにはインストール済みのはずです）
• ホームディレクトリに.dbtという名前のフォルダーを作成します
• ~/.dbt/フォルダー内に、このサンプルプロファイルのようなprofiles.ymlファイルが必要です
• 最小のウェアハウスを環境変数として保存します。dbtジョブはウェアハウスを識別するための変数名としてSNOWFLAKE_TRANSFORM_WAREHOUSEを使用します。環境変数は次のように.bashrcまたは.zshrcファイルで設定できます:
  • export SNOWFLAKE_TRANSFORM_WAREHOUSE="DEV_XS"
  • より多くのコンピュートが必要な場合、この変数は実行時に上書きできます。次のセクションでその方法を説明します。
• analyticsプロジェクトをクローンします
• Linuxで実行する場合:
  • Rancher Desktopがインストールされていることを確認します

これらのステップの多くは、新しいアナリストが実行することを推奨するオンボーディングスクリプトで行われます。

dbt実行時に適切なSnowflakeウェアハウスを選択する

Snowflakeインスタンスには複数のサイズのウェアハウスが含まれており、dbt開発者がクエリに割り当てるコンピュートリソースを異なるレベルで設定できます。ウェアハウスが大きくなり、実行時間が長くなるほど、クエリのコストが高くなります。例えば、X-Smallウェアハウスを1時間実行するコストと比較して、Largeウェアハウスを1時間実行するコストは8倍になります。

複数のウェアハウスにアクセスできる場合、profiles.ymlファイルに各ウェアハウスのエントリを作成できます。これにより、dbt runを呼び出す際に実行するウェアハウスを指定できます。これは慎重に行う必要があります。大きなウェアハウスを使用するとパフォーマンスは向上しますが、コストが大幅に増加します！小さいウェアハウスを使用する方向で判断してください。小さいウェアハウスのパフォーマンスが不十分な場合は、大きなウェアハウスで再試行する前に原因を調査してください。非効率なモデルを大きなウェアハウスに対して実行すると、開発中のコストが増加するだけでなく、モデルが本番環境で実行されるたびにコストが増加し、Snowflakeコストの意図しない継続的な増加をもたらします。

例

データチームのメンバーとして、dbtモデルに変更を加える必要があると想像してください。X-SmallウェアハウスとLargeウェアハウスの両方にアクセスでき、profiles.ymlファイルが次のように設定されています:

gitlab-snowflake:
  target: dev
  outputs:
    dev:
      type: snowflake
      threads: 8
      account: gitlab
      user: {username}
      role: {rolename}
      database: {databasename}
      warehouse: DEV_XS
      schema: preparation
      authenticator: externalbrowser
    dev_l:
      type: snowflake
      threads: 16
      account: gitlab
      user: {username}
      role: {rolename}
      database: {databasename}
      warehouse: DEV_L
      schema: preparation
      authenticator: externalbrowser

ターミナルとコードエディターを開き、新しいブランチを作成し、dbtモデルを調整して変更を保存します。変更をローカルでテストするためにdbtを実行する準備ができたので、次のコマンドを入力します: dbt run --models @{model_name}。dbtはモデルのビルドを開始し、デフォルトではANALYST_XSウェアハウスを使用してビルドします。しばらくすると、タイムアウトエラーによりビルドが失敗します。明らかに、ビルドしているモデルツリーには大きなまたは複雑なモデルが含まれています。クエリを完了させるには、より大きなウェアハウスを使用する必要があります。ビルドを再試行したいですが、今度はANALYST_XSの代わりにANALYST_Lウェアハウスを使用させたいです。そこでdbt run --models @{model_name} --target dev_lを入力します。これによりdbtに、profiles.ymlファイルのdev_lターゲットで指定したウェアハウスを使用するよう指示します。数分後にビルドが完了し、作業の確認を始めます。

Venv ワークフロー

Macシステムを使用している場合に推奨されるワークフローです。

dbtを使用する

• DBT_PROFILE_PATH環境変数が設定されていることを確認してください。onboarding_script.zsh（最新版で定期的に更新されているため使用を推奨）を使用した場合は設定されているはずですが、設定されていない場合は.bashrcまたは.zshrcにexport DBT_PROFILE_PATH="/<your_root_dir/.dbt/"を追加するか、ローカルターミナルセッションで同じコマンドを実行することで設定できます

• 特定のユーザー設定で.dbt/profiles.ymlを更新していることを確認してください

• GitLabの方向に従ってSSH設定がセットアップされていることを確認してください。鍵は~/.ssh/にあり、パスワードなしで生成されているべきです。

  • メインプロジェクトでdbt depsを実行するにはこのプロジェクトへのアクセスも必要です。

• 注意: デフォルトのブラウザをChromeに設定してください。組み込みのSSOログインはChromeでのみ動作します

• 注意: /analyticsリポジトリがある場所のフォルダーにいることを確認してください。すべてを正しくインストールしていれば、jump analyticsでdbtコマンドを正常に実行するために必要な場所に移動できます

• 注意: dbtを初めて実行する前にmake prepare-dbtを実行してください。これにより、venvがインストールされます。

• dbtコンテナを起動してその中のシェルからコマンドを実行するには、make run-dbtを使用してください。このコマンドはdbtの実行に必要な依存関係をインストールまたは更新します。

• 依存関係のアップデートなしにdbtコンテナを起動するにはmake run-dbt-no-depsを使用してください。このコマンドはdbtの依存関係がすでにインストールされていることを前提としています。

• これにより、ローカルのprofiles.ymlとリポジトリファイルを含む、dbtが実行に必要なすべてのものが自動的にインポートされます

• 現在のブランチのdocsを表示するには、make run-dbt-docsを実行してからWebブラウザでlocalhost:8081にアクセスしてください

なぜローカルdbt開発に仮想環境を使用するのか？

ローカルdbt開発に仮想環境を使用するのは、すべての開発者がまったく同じdbtバージョンとまったく同じ依存関係を実行することを確保するためです。これにより、異なるソフトウェアバージョンによる開発者の異なる開発体験のリスクを最小化し、全員のソフトウェアを同時にアップグレードするのが簡単になります。さらに、ステージングと本番環境はコンテナ化されているため、このアプローチにより同じコードがすべての環境で可能な限り予測可能に実行されることが保証されます。

ローカルで変更をビルドする

ローカル開発スペースで変更されたすべてのモデルをクローンしてビルドするには、CIジョブで使用されているbuild_changesプロセスと同じものを使用できます。主な違いは、WAREHOUSE変数の代わりに開発者が異なるウェアハウスサイズで設定されたターゲットを使用するためのTARGET変数を渡すことができる点です。プロセスを実行するには、仮想環境内からmake build-changesコマンドを実行してください。

 ~/repos/analytics/transform/snowflake-dbt
╰─$ make build-changes DOWNSTREAM="+1" FULL_REFRESH="True" TARGET="dev_xl" VARS="key":"value" EXCLUDE="test_model"

ビデオ紹介

SQLFluff リンター

SQLFluffを使用して、コードにSQLスタイルガイドを適用します。dbt仮想環境内ではmake lint-modelsを使用できます。デフォルトではlint-modelsプロセスは変更されたすべてのsqlファイルをリントしますが、MODEL変数を使用して特定のsqlファイルをリントしたり、FIX変数を使用してsqlファイルに変更を加えるlinterのfixコマンドを実行したりできます。

~/repos/analytics/transform/snowflake-dbt
╰─$ make lint-models
sqlfluff lint models/workspaces/workspace_data/mock/data_type_mock_table.sql

~/repos/analytics/transform/snowflake-dbt
╰─$ make lint-models FIX="True" MODEL="dim_date"
sqlfluff fix ./models/common/dimensions_shared/dim_date.sql

ビデオ紹介

ローカルでのSAFEチェック

モデルのSAFEカバレッジをテストするには、CIジョブで使用されているsafe_model_scriptプロセスと同じものを使用できます。仮想環境内からmake safe-checkコマンドを実行してください。

 ~/repos/analytics/transform/snowflake-dbt
╰─$ make safe-check

ローカルでモデルをクローンする

このコマンドにより、dbt選択構文を使用してゼロコピークローニングで完全なリネージをクローンできます。これはdbtを使ってモデルを実行するよりもはるかに速くコスト効率が高いですが、dbtの検証は実行しません。そのため、すべてのdbtユーザーはこのコマンドを使用して環境をセットアップすることをお勧めします。

前提条件:

• dbtがセットアップされていてモデルを実行できることを確認してください
• これらのローカルコマンドは/.dbt/profiles.ymlで設定されているSnowflakeユーザーを使用して実行され、ユーザーに権限のないテーブルはスキップします
• これらのコマンドは、dbt CIパイプラインと同じロジックを使用し、DBT_MODELS変数を使用して特定のリネージを選択します
• これらのコマンドを実行するには/analyticsディレクトリにいる必要があります

使用法:

新しいclone-dbt-select-local-user-noscriptコマンドを使用するには、DBT_MODELS変数を指定する必要があります。例えば、dim_subscriptionモデルのみをクローンするには次のコマンドを実行します:

make DBT_MODELS="dim_subscription" clone-dbt-select-local-user-noscript

これにより、dbtモデルがprodブランチからローカルユーザーデータベース（{user_name}_PROD）にクローンされます。dbtセレクター（@、+など）を使用して、ローカルデータベースにコピーしたいリネージ全体を選択できます。

本番オーケストレーション

本番環境のdbtモデルはApache Airflowを使用してオーケストレーションされます。各スケジュールされたパイプラインはKubernetesポッド内のAirflow DAGとして実行され、dbtコマンドをSnowflakeに対して実行します。

現在の状態

各本番パイプラインは、extractリポジトリのdags/transformationディレクトリ内の個別のPythonファイルとして定義されています。

将来の状態（進行中）

オーケストレーションは頻度ベースのDAGによるdbtモデルオーケストレーションの標準化イニシアチブの一環として、設定駆動システムに移行中です。

設定駆動のDAG生成

新しいPython DAGファイルを各パイプラインに書く代わりに、ジョブ定義は単一のYAMLマニフェスト（dbt_jobs_manifest.yml）に一元化されます。

各ジョブエントリは以下をサポートしています:

• schedule – DAGが実行されるタイミングを定義するcron式
• exclusion_schedule – スキップする日付や曜日のためのオプションのcron式
• warehouse – ジョブのデフォルトのSnowflakeウェアハウス
• tasks – dbtステップの順序付きリスト

モデルレベルの頻度設定

長期的なビジョンは、各dbtモデルがconfig.meta.frequency値を使用して独自のリフレッシュケイデンスを宣言することです。

サポートされている頻度の値:

Dockerワークフロー

以下は、venvワークフローの前提条件が少なくかなり速いため、主にLinuxを使用しているユーザーに推奨されるワークフローです。

メインのanalyticsプロジェクトはDockerコンテナ内からdbtを使用することをサポートしています。data-imageプロジェクトからコンテナをビルドします。

最初の実行前（およびコンテナが更新されるたびに）、以下のコマンドを実行してください:

1. make update-containers
2. make cleanup

コマンドラインチートシート

dbt固有:

• dbt clean - /dbt_modules（depsを実行したときに生成）と/targetフォルダー（モデルを実行したときに生成）を削除します
• dbt run - 通常の実行
• モデル選択構文（source）:
  • dbt run --models modelname - modelnameのみを実行
  • dbt run --models +modelname - modelnameとすべての親を実行
  • dbt run --models modelname+ - modelnameとすべての子を実行
  • dbt run --models +modelname+ - modelname、すべての親と子を実行
  • dbt run --models @modelname - modelname、すべての親、すべての子、すべての子の親を実行
  • dbt run --exclude modelname - modelname以外のすべてのモデルを実行
• dbt run --full-refresh - 増分モデルをリフレッシュ
• dbt test - カスタムデータテストとスキーマテストを実行
• dbt seed - data-pathsディレクトリで指定されたcsvファイルをデータウェアハウスに読み込む
• dbt compile - モデル内のテンプレートコードをコンパイルして結果をtarget/フォルダーに出力

スタイルと使用ガイド

モデル構造

Kimball式のウェアハウスへの移行に伴い、ウェアハウスとプロジェクト構造内でのモデルの整理方法を改善しています。

ソース

すべての生データは引き続きSnowflakeのRAWデータベースにあります。これらの生テーブルはsource tablesまたはraw tablesと呼ばれます。

ソースはdbtでsources.ymlファイルを使用して定義されます。

ソースモデル

すべての生データの上に非常に薄いソース層を実施しています。このディレクトリはほとんどのソース固有の変換が保存される場所です。

ソースモデルで行うべきこと:

• フィールドをユーザーフレンドリーな名前に変更
• 適切な型に列をキャスト
• 今後も100%確実に有用な最小限の変換
• 論理的に名付けられたスキーマへの配置

ソースモデルで行うべきでないこと:

• データの削除
• 他のテーブルへの結合
• 列の意味を根本的に変える変換

センシティブデータ

場合によっては、生の値を公開すべきでない列があります。これには顧客のメールや名前などが含まれます。

スタティックマスキング

スタティックマスキングを使用する特定のモデルでは、ソース形式が上記のように従われます。列はソースモデルでハッシュされません。

機密列はschema.ymlファイルでmetaキーを使用してsensitiveをtrueに設定してドキュメント化されます。

ダイナミックマスキング

機密データを一部のユーザーには公開し、他のユーザーには公開しない場合、ダイナミックマスキングを適用できます。

ステージング

Kimballモデリングの実装前は、ほとんどすべてのモデルがステージングカテゴリに分類されていました。

ワークスペース

dbtプロジェクト内に、すべてのコーディングとスタイルガイドに準拠する必要のないチーム固有のコードのためのスペースを提供しています。

全般

• モデル名はできるだけ明確にし、可能な限り完全な単語を使用します（例: acctsではなくaccounts）。
• 新しいdbtモデルのドキュメント化とテストはそれらを作成するプロセスの一部です。テストとドキュメントなしに新しいdbtモデルは完成しません。
• すべての{{ ref('...') }}ステートメントはファイルの先頭のCTEに配置する必要があります。

モデル設定

• デフォルトのマテリアライゼーションはviewです
• デフォルトのスキーマはprep.preparationです
• モデルの無効化は常にdbt_project.yml内で+enabled: false宣言を使用して行う必要があります

シード

シードはdbtドキュメントに従ってcsvファイルからデータウェアハウスにデータを読み込む方法です。

タグ

dbtのタグは、プロジェクトの異なる部分にラベルを付ける方法です。

ウェアハウスサイズ

モデル内のウェアハウスサイズの設定は、モデルに必要なパフォーマンスを確保する方法です。

信頼できるデータフレームワーク

信頼できるデータフレームワーク（TDF）の哲学についての詳細は、プラットフォームページの信頼できるデータフレームワークセクションを参照してください。

スキーマからゴールデンデータカバレッジ

12のカテゴリのTDFモニターとテストを実装しています:

1. 新鮮度モニター テーブルとフィールドの更新における異常な遅延を監視
2. スキーマモニター 追加、削除、変更されたフィールドを監視
3. ボリュームモニター 行数に基づくテーブルサイズの異常な変化を監視
4. フィールドヘルスモニター nullの割合、ユニークの割合などの統計のディップやスパイクを監視
5. SQLルールモニター 1つ以上のテーブルにわたって任意の条件をチェックするSQL文を記述
6. JSONスキーマモニター テーブルフィールドに追加されたJSONデータのスキーマ変更を監視
7. ディメンショントラッキング 低カーディナリティのテーブルフィールド内の値の分布の変化を監視
8. スキーマテスト
9. カラム値テスト
10. 行数テスト
11. カスタムSQL

スキーマテスト

スキーマテストは、既知のテーブル、列、その他のスキーマ構造の存在を検証するように設計されています。

カラム値テスト

カラム値テストは、列のデータ値が事前定義された閾値内にあるか、既知のリテラルと一致するかを判断します。

行数テスト

行数テストは、一定期間にわたるテーブルの行数が期待される事前定義された結果を満たすかを判断する特殊なタイプのカラム値テストです。

カスタムSQL

上記のカテゴリのいずれにも適合しないテストを考えている場合は、任意のSQLをテストとして書くこともできます。重要な点は、行が返されない場合にテストが合格することです。

dbtモデルのドキュメント化

ドキュメントはすべてのdbtモデルの第一級の要件です。スタイルと使用ガイドで述べているように: テストとドキュメントなしに新しいdbtモデルは完成しません。

なぜドキュメントが重要か

現在、約25%のモデルと1%未満のソース列にのみ説明があります。このギャップには2つの具体的なコストがあります: 開発者はカタログでその情報を見つけるのではなく、モデルの粒度とビジネスロジックを理解するためにSQLを読まなければならず、説明がない場合にAI支援開発ツールが頼れる意味的なコンテキストがほとんどありません。

規約の概要

モデルの説明

5セクションテンプレート

すべてのモデルの説明は以下の構造を使用した{% docs %}ブロックとして記述されます:

{% docs model_name %}

**説明:** モデルが含むものとその目的を説明する1〜2文。

**データ粒度:**
- プライマリキーの列 - 各行を一意にするディメンションごとに1つの箇条書き

**モデルに適用されるフィルター:**
- アクティブなフィルターごとに別々の箇条書き。フィルターがアップストリームモデルから来ており、ここで再実装されていない場合は`Inherited`を接頭辞として付けます。

**このモデルのビジネスロジック:**
- 主要な変換、導出、またはJoinロジック。

**その他のコメント:**
- 注意点、既知のエッジケース、IssueやHandbookエントリへのリンク。

{% enddocs %}

スナップショット

dbtスナップショットは、可変（SCDタイプ1）ソーステーブルの上に構築されたSCDタイプ2テーブルで、ソーステーブルへの変更を時間の経過とともに記録します。

スナップショットのベストプラクティス

• データベースとスキーマの設定: dbt_project.ymlでデータベースとスキーマを設定します。
• 命名規則に従う: データウェアハウスのテーブル名は{source_table_name}_snapshotsの命名規則に従う必要があります。
• 変換を避ける: 重複排除以外のスナップショットモデルでは最小限の変換を実行します。

スナップショットとGDPR

時々、データチームはGDPRのためにSnowflakeデータウェアハウスから個人データを削除するリクエストを受けます。これらの削除に対処するために、dbtマクロを使用します。詳細はgdpr-deletionsページを参照してください。

モデルの効率性

モデルの効率性とは、モデルがSnowflakeリソースをどれだけうまく使用してモデルを生成するかの測定値です。

方法

各モデルについて、実行されたクエリは最初にフィルタリングと集計が行われます。CREATE_VIEW, INSERT, DELETE, CREATE_TABLE_AS_SELECT, MERGE, CREATE_VIEW, SELECT, EXTERNAL_TABLE_REFRESHの特定のクエリタイプのみが考慮されます。

ローカルストレージ効率

\[E_l = min{\frac{s-S_l}s,0}\]

リモートストレージ効率

\[E_r = min{\frac{s-S_r}s,0}\]

パーティションスキャン効率

\[E_p = if\ p\ >\ 1\ then\ min{\frac{p-S_p}p,0}\ else\ 1\]

効率スコア

\[E = [(E_l * w_l) + (E_r * w_r) + (E_p * w_p)]*100\]

モデルパフォーマンス

パフォーマンスはモデルの実行時間（Snowflakeクレジットに直接影響）と開発者の時間（開発者が待つ時間に影響）の間でバランスを取る必要があります。データウェアハウスの全体的なパフォーマンス目標:

• すべてのモデルは個別に60分未満で実行する必要があります。
• すべてのモデルは許容される最小のウェアハウスで実行する必要があります。

カテゴリ分類

モデル実行時間

モデルサイズ

モデル効率性

dbtのアップグレード

runbookを参照してください。

最新状態を維持する

私たちのポリシーは、クリティカルサポートのあるdbt-coreのバージョンを常に使用することです。

dbtアップグレードのスケジュール

dbtのアップグレードは、大きな世界的な祝日やファミリーアンドフレンズデーのない週の火曜日に行う必要があります。

dbtモデルレベルでのウェアハウスサイズの指定

新しいproductとnon-productモデルは今後デフォルトで’L’ウェアハウスサイズを使用します。

dbtモデルレベルでウェアハウスを指定するには（デフォルトのウェアハウスを上書き）、モデルに設定ブロックを追加する必要があります:

{{ config(
    snowflake_warehouse=generate_warehouse_name('XL')
) }}

ウェアハウスの正しいサイズ選択については、このページの「ウェアハウスサイズの実行可能性の確認」セクションを参照してください。

ページのソースコードを見る - ページの編集 - please contribute.