このドキュメントでは、Dataform リポジトリに関する次の情報について説明します。
Dataform のリポジトリのベスト プラクティスの概要
このセクションでは、Dataform でリポジトリ サイズ、リポジトリ構造、コード ライフサイクルを管理するベスト プラクティスの概要を示します。
リポジトリ サイズのベスト プラクティス
リポジトリ サイズは、次のような Dataform における開発のさまざまな側面に影響します。
- コラボレーション
- コードベースの読みやすさ
- 開発プロセス
- ワークフロー コンパイル
- ワークフローの実行
Dataform では、コンパイルのリソースに API の割り当てと制限を適用します。リポジトリ サイズが大きいと、リポジトリでこれらの割り当てと上限を超えることがあります。これにより、ワークフローのコンパイルと実行が失敗する可能性があります。
このリスクを軽減するために、大規模なリポジトリを分割することをおすすめします。大規模なリポジトリを分割する場合、大規模なワークフローを、各リポジトリに格納され、さらにリポジトリ間の依存関係で接続される多数の小規模なワークフローに分割します。
このアプローチにより、Dataform の割り当てと上限を遵守し、プロセスと権限を詳細に制御して、コードベースの読みやすさとコラボレーションを改善できます。ただし、分割リポジトリの管理は、単一のリポジトリの管理よりも困難になる場合があります。
Dataform でのリポジトリ サイズの影響については、リポジトリ サイズの概要をご覧ください。リポジトリ分割のベスト プラクティスの詳細について、リポジトリの分割を確認する。
リポジトリ構造のベスト プラクティス
definitions ディレクトリ内のファイルは、ワークフローのステージを反映するように構成することをおすすめします。ニーズに最適なカスタム構造を採用できる点にもご留意ください。
推奨される次の definitions サブディレクトリの構造は、ほとんどのワークフローの主なステージを反映しています。
sources: データソース宣言を格納します。- データ変換ロジックを保存するための
intermediate。 output: 出力テーブルの定義を格納します。extras（省略可）: 追加のファイルを格納します。
Dataform 内のすべてのファイル名は、BigQuery テーブルの命名ガイドラインに準拠している必要があります。Dataform リポジトリの definitions ディレクトリ内のファイル名は、サブディレクトリ構造を反映することをおすすめします。
リポジトリ内のファイルを構造化および命名するためのベスト プラクティスについて詳しくは、リポジトリ内のコードの構造化をご覧ください。
コード ライフサイクルのベスト プラクティス
Dataform のデフォルトのコード ライフサイクルは、次のフェーズで構成されています。
Dataform ワークスペースでのワークフロー コードの開発。
Dataform コアまたは JavaScript のみで開発できます。
ワークフロー設定ファイルの設定を使用して、コードをコンパイル結果にコンパイルします。
リリース構成とワークスペースのコンパイル オーバーライドを使用して、カスタム コンパイル結果を構成できます。
リリース構成を使用すると、リポジトリ全体のカスタム コンパイル結果を構成できます。後で、ワークフロー構成で実行をスケジュールできます。
ワークスペース コンパイル オーバーライドを使用すると、リポジトリ内のすべてのワークスペースに対してコンパイルのオーバーライドを構成し、各ワークスペースのカスタム コンパイル結果を作成できます。
BigQuery でのコンパイル結果の実行。
ワークフロー構成を使用して、実行またはリポジトリのコンパイル結果をスケジュールできます。
Dataform でコード ライフサイクルを管理するには、開発、ステージング、本番環境などの実行環境を作成します。
Dataform のコード ライフサイクルの詳細については、Dataform のコード ライフサイクルの概要をご覧ください。
実行環境を単一のリポジトリに保持するか、複数のリポジトリに保持するかを選択できます。
単一のリポジトリ内の実行環境
ワークスペースのコンパイルのオーバーライドとリリース構成を使用して、分離された実行環境（開発、ステージング、本番環境など）を 1 つの Dataform リポジトリ内に作成できます。
分離された実行環境は次の方法で作成できます。
- スキーマごとに開発テーブルと本番環境テーブルを分割します。
- スキーマと Google Cloud プロジェクトごとに開発テーブルと本番環境テーブルを分割します。
- 開発、ステージング、本番環境のテーブルを Google Cloud プロジェクトごとに分割します。
その後、ワークフロー構成を使用して、ステージング環境と本番環境で実行をスケジュールできます。開発環境では、手動で実行をトリガーすることをおすすめします。
Dataform でのワークフロー ライフサイクルの管理に関するベスト プラクティスの詳細については、ワークフロー ライフサイクルのベスト プラクティスをご覧ください。
複数のリポジトリのコード ライフサイクル
コード ライフサイクルの各ステージに合わせて Identity and Access Management の権限を調整するには、リポジトリの複数のコピーを作成して、それらを各 Google Cloud プロジェクトに保存します。
各 Google Cloud プロジェクトは、コード ライフサイクルのステージ（開発や本番環境など）に対応する実行環境として機能します。
このアプローチでは、すべてのプロジェクトでリポジトリのコードベースを同じにすることをおすすめします。リポジトリの各コピーでコンパイルと実行をカスタマイズするには、ワークスペースのコンパイルのオーバーライド、リリース構成、ワークフロー構成を使用します。
リポジトリ サイズの概要
このセクションでは、リポジトリ サイズがワークフロー開発と Dataform コンパイル リソースの使用量に与える影響と、リポジトリのコンパイル リソースの使用量を推定する方法について説明します。
Dataform のリポジトリ サイズについて
リポジトリのサイズは、Dataform での開発の次の側面に影響します。
コラボレーション。大規模なリポジトリで複数の共同編集者が作業すると、プルリクエストの数が過剰になり、マージ競合のリスクが高まります。
コードベースの読みやすさ。1 つのリポジトリ内のワークフローを構成するファイルの数が多くなると、リポジトリのナビゲーションが困難になる可能性があります。
開発プロセス。単一リポジトリ内の大規模なワークフローの一部では、ワークフローの残りの部分に適用される権限やプロセスとは異なる、カスタム権限やプロセス（スケジューリングなど）が必要になることがあります。リポジトリのサイズが大きいと、ワークフローの特定の領域に合わせて開発プロセスを調整することが難しくなります。
ワークフローのコンパイル。Dataform では、コンパイル リソースに使用量上限が適用されます。リポジトリ サイズが大きいと、これらの上限を超えてコンパイルが失敗する可能性があります。
ワークフローの実行。実行中、Dataform はワークスペース内のリポジトリ コードを実行し、アセットを BigQuery にデプロイします。リポジトリが大きいほど、Dataform の実行に時間がかかります。
リポジトリのサイズが大きいことが Dataform での開発に悪影響を及ぼしている場合は、リポジトリを複数の小さなリポジトリに分割できます。
リポジトリ コンパイルのリソースの上限について
開発中に、Dataform はワークスペース内のすべてのリポジトリ コードをコンパイルし、リポジトリ内のワークフローの表現を生成します。これをコンパイル結果と呼びます。Dataform ではコンパイル リソースに使用量上限が適用されます。
リポジトリが使用量上限を超える理由としては、次のことが考えられます。
- リポジトリ コードの無限ループ バグ。
- リポジトリ コードのメモリリーク バグ。
- リポジトリ サイズが大きい（ワークフロー アクションの数が約 1000 個を超える）。
コンパイル リソースの使用量上限の詳細については、Dataform コンパイルのリソースの上限をご覧ください。
リポジトリのコンパイル リソースの使用量を推定する
リポジトリの次のコンパイル リソースの使用量を推定できます。
- CPU 時間の使用量。
- リポジトリで定義されたアクションの生成済みグラフのシリアル化された合計最大データサイズ。
リポジトリのコンパイルの現在のコンパイル CPU 時間の使用状況を大まかに得るには、ローカルの Linux または macOS マシンで Dataform ワークフローのコンパイルの時間を計測します。
ワークフローのコンパイルの時間を計測するには、リポジトリ内で次の形式で Dataform CLI コマンド
dataform compileを実行します。time dataform compile次のコードサンプルは、
time dataform compileコマンドを実行した結果を示しています。real 0m3.480s user 0m1.828s sys 0m0.260s
real の結果は、リポジトリのコンパイルの CPU 時間の使用状況を大まかに示す指標として扱うことができます。
リポジトリで生成されたアクションのグラフの合計サイズを概算で取得するには、グラフの出力を JSON ファイルに書き込むことができます。非圧縮 JSON ファイルのサイズは、グラフの合計サイズのおおよその目安として使用できます。
ワークフローのコンパイル済みグラフの出力を JSON ファイルに書き込むには、リポジトリ内で次の Dataform CLI コマンドを実行します。
dataform compile --json > graph.json
リポジトリの分割
このセクションでは、Dataform リポジトリを分割し、リポジトリ間の依存関係を管理するための戦略について説明します。
リポジトリは Dataform のコア単位です。リポジトリには、ワークフローを構成するすべての SQLX ファイルと JavaScript ファイル、Dataform 構成ファイルとパッケージが格納されます。ワークフローは 1 つのリポジトリに保存することも、複数のリポジトリに分割することもできます。
Dataform でリポジトリを分割すると、次のようなメリットがあります。
- コンパイル リソースの使用に関する Dataform の上限を遵守する。大規模なワークフローを複数の小さなリポジトリに分割すると、コンパイル リソースに関する Dataform の上限を超えるリスクが軽減されます。
- プロセスを細分化します。継続的インテグレーション（CI）ルールなどのプロセスは、ワークフローの分割されたフラグメントと、それを開発するチームごとに個別に設定できます。
- 権限のきめ細かい設定。ワークフローの各分割フラグメントと、それを開発するチームに対して個別に権限を設定することで、ワークフローの全体的なセキュリティを強化できます。
- ワークフローの分割された各フラグメントで作業する共同編集者の数を最小限に抑えることで、コラボレーションを改善する。
- コードベースの可読性を向上させる。大規模なワークフローを構成するファイルを複数のリポジトリに分割すると、ワークフロー全体を一度にナビゲートするよりも、各リポジトリを個別にナビゲートしやすくなります。
- ワークフロー全体を実行する場合と比較して、ワークフローの各スプリット フラグメントのワークフロー実行を高速化します。
Dataform でリポジトリを分割すると、次のようなデメリットがあります。
- 各 Dataform リポジトリおよび対応する Git リポジトリ用にカスタムの継続的インテグレーションと継続的開発（CI/CD）の構成が必要。
- 各 Dataform リポジトリおよび対応する Git リポジトリ用にカスタム スケジューリング構成が必要。
- 複数のリポジトリに格納されているワークフローのオブジェクト間の依存関係の管理が難しい。
- 複数のリポジトリに分割された SQL ワークフローの包括的な有向非巡回グラフ（DAG）の可視化が不足している。各リポジトリで生成された DAG は、完全なワークフローの一部を表すだけに留まる。
リポジトリを分割するための戦略
リポジトリを分割すると、親 SQL ワークフローを構成するファイルが、個別の Dataform リポジトリに格納されている小さな子ワークフローに分割されます。
リポジトリを分割する方法は次のとおりです。
- 開発チームごとに 1 つのリポジトリ。
- ドメインごとに 1 つのリポジトリ（販売、マーケティング、ロジスティクスなど）。
- 1 つの中央リポジトリと、中央リポジトリのコンテンツをデータソースとして使用するドメインごとに 1 つのリポジトリ。
親ワークフローをサードパーティの Git ホスティング プラットフォームに配置するには、子ワークフローを含む個別のリポジトリを、専用のサードパーティの Git リポジトリに個別に接続する必要があります。
クロスリポジトリの依存関係を管理する
リポジトリを分割する最も効率的な方法は、親 SQL ワークフローを自己完結型の子ワークフローに分割し、独立したリポジトリを作成することです。独立したリポジトリは、別のリポジトリの内容をデータソースとして使用しません。このアプローチでは、リポジトリ間の依存関係を管理する必要はありません。
リポジトリ間の依存関係を回避できない場合は、リポジトリを連続するリポジトリに分割して管理できます。この場合、リポジトリは先行リポジトリに依存し、後続リポジトリのデータソースになります。リポジトリとその依存関係の継承は、親ワークフローの構造を最もよく反映している必要があります。
Dataform データソース宣言を使用して、リポジトリ間の依存関係を作成できます。別の Dataform リポジトリの BigQuery テーブルタイプを、編集中のリポジトリのデータソースとして宣言できます。データソースを宣言したら、他の Dataform ワークフロー アクションと同様に参照して、ワークフローの開発に使用できます。
リポジトリ間で分割されたワークフローの実行をスケジュールし、リポジトリ間の依存関係がある場合は、リポジトリ間の依存関係の順にリポジトリを 1 つずつ実行する必要があります。
リポジトリを双方向の依存関係を持つリポジトリのグループに分割することは避けることをおすすめします。リポジトリ間の双方向の依存関係は、あるリポジトリが別のリポジトリのデータソースであり、そのリポジトリをデータソースとしても使用する場合に発生します。リポジトリ間の双方向の依存関係により、親ワークフローのスケジューリングと実行、開発プロセスが複雑になります。
リポジトリ内のコードの構造化
このセクションでは、Dataform リポジトリのルート definitions ディレクトリにあるワークフロー ファイルを構造化して命名するためのベスト プラクティスについて説明します。推奨される definitions ディレクトリの構造は、ワークフローのステージを反映しています。ビジネスニーズに合った構造を採用できます。
definitions ディレクトリにワークフロー コードを構造化する理由としては、次のようなものがあります。
- ワークフローの一部にチームを割り当てることで、コードベースでのコラボレーションを改善する。
- 組織の変更が発生した場合のワークフローの保守性を向上させます。
- コードベース内のナビゲーションを改善する。
- コードベースの拡張性を改善する。
- チームの管理オーバーヘッドを最小限に抑える。
definitions ディレクトリの推奨構造
Dataform リポジトリのルート definitions ディレクトリには、ワークフローの要素を作成するコードが含まれています。definitions ディレクトリ内のファイルは、ワークフローの構造を反映したディレクトリ構造に整理できます。
ワークフローを開発するときは、ソーステーブルを宣言して変換し、ビジネスや分析に使用できる出力テーブルを作成します。
ワークフローの 3 つの主要なステージを区別できます。
- データソースの宣言。
- ソースデータの変換。
- 変換されたソースデータから出力テーブルの定義。
definitions ディレクトリのサブディレクトリの次の構造は、ワークフローの主なステージを反映しています。
sources- データソースの宣言とソースデータの基本的な変換（フィルタリングなど）。
intermediatesourcesから読み取り、変換されたデータを使用してoutputsテーブルを定義する前にデータを変換するテーブルとアクション。通常、Dataform が BigQuery に実行した後、ビジネス インテリジェンス（BI）ツールなどの追加のプロセスやツールに公開されないテーブル。outputs- Dataform が BigQuery で実行した後に、BI などのプロセスやツールで使用されるテーブルの定義。
extra- ワークフローのメイン パイプライン外のファイル（機械学習などの追加用途のために準備されたワークフロー データを含むファイルなど）。省略可能なカスタム サブディレクトリ。
sources のベスト プラクティス
sources サブディレクトリには、ワークフローの最初のステージ（ソースデータの宣言と基本的な変換）が含まれています。
sources サブディレクトリに、列のフィルタ、分類、キャスト、名前変更を行うデータソース宣言とテーブルを保存します。
複数のソースのデータを結合するテーブルの保存は避けてください。
intermediate サブディレクトリに保存されているテーブルの sources データを変換します。
複数のプール（Google 広告や Google アナリティクスなど）からデータソースを宣言する場合は、各プール専用のサブディレクトリを作成します。
次のサンプルは、2 つのソースプールを含む sources のサブディレクトリ構造を示しています。
definitions/
sources/
google_ads/
google_ads_filtered.sqlx
google_ads_criteria_metrics.sqlx
google_ads_criteria_metrics_filtered.sqlx
google_ads_labels.sqlx
google_ads_labels_filtered.sqlx
google_analytics/
google_analytics_users.sqlx
google_analytics_users_filtered.sqlx
google_analytics_sessions.sqlx
同じスキーマ内で複数のデータソース テーブルを宣言する場合は、宣言を 1 つの JavaScript ファイルに統合できます。
JavaScript を使用してデータソース宣言を作成する方法については、JavaScript のみを使用してワークフローを作成するをご覧ください。
次のコードサンプルは、1 つのスキーマ内の複数のデータソースを 1 つの JavaScript ファイルで宣言する方法を示しています。
[
"source_table_1",
"source_table_2",
"source_table_3"
].forEach((name) =>
declare({
database: "gcp_project",
schema: "source_dataset",
name,
})
);
データソースの変更からワークフローを保護するには、データソースの宣言ごとにビュー（analytics_users_filtered.sqlx など）を作成します。ビューには、ソースデータの基本的なフィルタリングと形式設定を含めることができます。ビューを sources サブディレクトリに保存します。
次に、intermediate テーブルまたは outputs テーブルを作成するときに、元のソーステーブルではなくビューを参照します。このアプローチでは、ソーステーブルをテストできます。ソーステーブルが変更された場合は、フィルタを追加したり、データを再キャストしたりするなど、ビューを変更できます。
intermediate のベスト プラクティス
intermediate サブディレクトリには、ワークフローの第 2 段階（1 つ以上のソースからのソースデータの変換と集計）が含まれています。
intermediate サブディレクトリには、sources サブディレクトリにある 1 つ以上のソースからソースデータを大幅に変換するファイル（データを結合するテーブルなど）を保存します。intermediate サブディレクトリ内のテーブルは通常、ソーステーブルまたは他の intermediate テーブルからデータをクエリします。
intermediate テーブルを使用して outputs テーブルを作成します。通常、Dataform が intermediate テーブルを BigQuery に実行した後、追加の目的（データ分析など）で使用されることはありません。intermediate テーブルは、出力テーブルの作成を可能にするデータ変換ロジックと考えることができます。
すべての intermediate テーブルを文書化してテストすることをおすすめします。
outputs のベスト プラクティス
outputs サブディレクトリには、ワークフローの最終段階である、変換されたデータからビジネス目的の出力テーブルを作成する処理が含まれています。
outputs ディレクトリには、Dataform が BigQuery に実行した後に、追加のプロセスやツールで使用する予定のテーブル（レポートやダッシュボードなど）を保存します。outputs ディレクトリ内のテーブルは通常、intermediate テーブルからデータをクエリします。
関連するビジネス エンティティ（マーケティング、注文、分析など）で outputs テーブルをグループ化します。各事業体にサブディレクトリを割り当てます。
出力テーブルを BigQuery に個別に保存するには、出力テーブル専用のスキーマを構成します。テーブル スキーマを構成する手順については、テーブル設定をオーバーライドするをご覧ください。
次のサンプルは、sales と marketing のビジネス エンティティを含む outputs のサブディレクトリ構造を示しています。
definitions/
outputs/
orders/
orders.sqlx
returns.sqlx
sales/
sales.sqlx
revenue.sqlx
marketing/
campaigns.sqlx
すべての outputs テーブルを文書化してテストすることをおすすめします。
命名戦略
Dataform 内のすべてのファイル名は、BigQuery テーブルの命名ガイドラインに準拠している必要があります。
Dataform リポジトリの definitions ディレクトリ内のファイル名は、サブディレクトリ構造を反映することをおすすめします。
sources サブディレクトリでは、ファイル名はそのファイルに関連するソースを指している必要があります。ソースの名前をファイル名の接頭辞として追加します（例: analytics_filtered.sqlx）。
intermediate サブディレクトリでは、ファイル名でサブディレクトリを識別する必要があります。これにより、共同編集者は intermediate ファイルを明確に区別できます。一意の接頭辞を選択し、intermediate ディレクトリ内のファイルにのみ適用します（例: stg_ads_concept.sqlx）。
outputs サブディレクトリでは、ファイル名は簡潔にする必要があります（例: orders.sqlx）。異なるエンティティ サブディレクトリに同じ名前の outputs テーブルがある場合は、エンティティを識別する接頭辞（sales_revenue.sqlx や ads_revenue.sqlx など）を追加します。
次の例は、推奨される命名戦略に準拠したファイル名を含む definitions ディレクトリ内のサブディレクトリ構造を示しています。
definitions/
sources/
google_analytics.sqlx
google_analytics_filtered.sqlx
intermediate/
stg_analytics_concept.sqlx
outputs/
customers.sqlx
sales/
sales.sqlx
sales_revenue.sqlx
ads/
campaigns.sqlx
ads_revenue.sqlx
次のステップ
- Dataform のコード ライフサイクルと構成方法の詳細について、Dataform のコード ライフサイクルの概要を確認する。
- ワークフロー ライフサイクルのベスト プラクティスの詳細については、ワークフロー ライフサイクルのベスト プラクティスをご覧ください。
- Dataform コンパイルのリソースの上限の詳細については、Dataform コンパイルのリソースの上限をご覧ください。
- Dataform リポジトリをサードパーティの Git リポジトリに接続する方法については、サードパーティの Git リポジトリに接続するをご覧ください。
- Dataform のワークフローの詳細については、ワークフローの概要をご覧ください。