このドキュメントでは、Dataform リポジトリのルート definitions ディレクトリに SQL ワークフロー ファイルを構造化して命名する際のベスト プラクティスについて説明します。definitions ディレクトリの推奨される構造は、SQL ワークフローのステージを反映しています。ビジネスニーズに合った構造を採用できます。
次の理由から、definitions ディレクトリに SQL ワークフロー コードを構造化することをおすすめします。
- ワークフローの一部にチームを割り当てることで、コードベースでのコラボレーションを改善します。
- 組織の変更の場合の SQL ワークフローのメンテナンス性の向上。
- コードベース内のナビゲーションを改善する。
- コードベースのスケーラビリティを改善する。
- チームの管理オーバーヘッドを最小限に抑える。
definitions ディレクトリの推奨される構造
Dataform リポジトリのルート definitions ディレクトリには、SQL ワークフローの要素を作成するコードが含まれています。definitions ディレクトリ内のファイルを、ワークフローの構造を反映したディレクトリ構造に整理できます。
SQL ワークフローを開発する場合は、ソーステーブルを宣言し、変換して、ビジネスや分析に使用できる出力テーブルを作成します。
SQL ワークフローの主なステージは 3 つあります。
- データソースの宣言
- ソースデータの変換
- 変換されたソースデータからの出力テーブルの定義
definitions ディレクトリのサブディレクトリの次の構造は、SQL ワークフローの主なステージを反映しています。
sources- データソースの宣言とソースデータの基本的な変換（フィルタリングなど）。
intermediatesourcesから読み取り、変換したデータをoutputsテーブルの定義に使用するテーブルとアクション。通常、テーブルは、Dataform が BigQuery にテーブルを実行した後、ビジネス インテリジェンス（BI）ツールなどの追加のプロセスやツールに公開されません。outputs- Dataform が BigQuery で実行した後、BI などのプロセスまたはツールで使用されるテーブルの定義。
extra- SQL ワークフローのメイン パイプライン外のファイル。たとえば、機械学習などの追加の使用のために準備されたワークフロー データを含むファイルなど。省略可能なカスタム サブディレクトリ。
sources のベスト プラクティス
sources サブディレクトリには、SQL ワークフローの最初のステージ（ソースデータの宣言と基本変換）が含まれています。
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 でデータソース宣言を作成する方法については、JavaScript を使用して Dataform SQL ワークフローを作成するをご覧ください。
次のコードサンプルは、1 つの JavaScript ファイルで宣言された 1 つのスキーマ内の複数のデータソースを示しています。
[
"source_table_1",
"source_table_2",
"source_table_3"
].forEach((name) =>
declare({
database: "gcp_project",
schema: "source_dataset",
name,
})
);
データソースの変更から SQL ワークフローを保護するには、データソース宣言ごとにビューを作成します（例: analytics_users_filtered.sqlx）。このビューには、ソースデータの基本的なフィルタリングとフォーマット設定を含めることができます。ビューを sources サブディレクトリに保存します。
次に、intermediate テーブルまたは outputs テーブルを作成するときに、元のソーステーブルではなくビューを参照します。このアプローチでは、ソーステーブルをテストできます。ソーステーブルが変更された場合は、フィルタの追加やデータの再キャストなど、ビューを変更できます。
intermediate のベスト プラクティス
intermediate サブディレクトリには、SQL ワークフローの第 2 ステージ（1 つ以上のソースからのソースデータの変換と集計）が含まれています。
intermediate サブディレクトリには、1 つ以上のソースからソースデータを大幅に変換するファイル（データを結合するテーブルなど）を sources サブディレクトリに保存します。通常、intermediate サブディレクトリ内のテーブルは、ソーステーブルまたは他の intermediate テーブルからデータをクエリします。
intermediate テーブルを使用して outputs テーブルを作成します。通常、intermediate テーブルは、Dataform が BigQuery に実行した後、データ分析などの追加の目的には使用されません。intermediate テーブルは、出力テーブルの作成を可能にするデータ変換ロジックと考えることができます。
すべての intermediate テーブルをドキュメント化してテストすることをおすすめします。
outputs のベスト プラクティス
outputs サブディレクトリには、SQL ワークフローの最後のステージ（変換されたデータからビジネス目的の出力テーブルを作成する）が含まれています。
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 での SQL ワークフローの詳細については、SQL ワークフローの概要をご覧ください。
- Dataform リポジトリの詳細については、リポジトリを作成するをご覧ください。
- リポジトリの分割の詳細については、リポジトリの分割の概要をご覧ください。