リポジトリ内のコードを構造化する

このドキュメントでは、Dataform リポジトリのルート definitions ディレクトリで SQL ワークフロー ファイルを構造化し、命名するためのベスト プラクティスについて説明します。definitions ディレクトリの推奨される構造は、SQL ワークフローの段階を反映しています。ビジネスニーズに合った構造を採用できます。

次のような場合は、definitions ディレクトリで SQL ワークフロー コードを構造化することをおすすめします。

  • ワークフローの選択した部分にチームを指定することで、コードベースのコラボレーションを改善します。
  • 組織が変更された場合の SQL ワークフローの保守性を改善します。
  • コードベース内のナビゲーションを改善する。
  • コードベースのスケーラビリティを改善する。
  • チームの管理オーバーヘッドを最小限に抑える。

Dataform リポジトリのルート definitions ディレクトリには、SQL ワークフローの要素を作成するコードが含まれています。definitions ディレクトリ内のファイルを、ワークフローの構造を反映するディレクトリの構造に整理できます。

SQL ワークフローを開発する場合、ソーステーブルを宣言し、変換してビジネスまたは分析に使用できる出力テーブルを作成します。

SQL ワークフローの 3 つの主要ステージを区別できます。

  1. データソースの宣言
  2. ソースデータの変換
  3. 変換されたソースデータからの出力テーブルの定義

definitions ディレクトリ内のサブディレクトリの構造は、SQL ワークフローの主要な段階を反映しています。

sources
データソースの宣言とソースデータの基本的な変換(フィルタリングなど)
intermediate
変換されたデータを使用して outputs テーブルを定義する前に、sources から読み取り、データを変換するテーブルとアクション。テーブルは通常、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

同じスキーマ内で複数のデータソース テーブルを宣言する場合は、その宣言を単一の 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 に保存するには、出力テーブル専用のスキーマを構成します。テーブル スキーマを構成する手順については、追加のテーブル設定の構成をご覧ください。

次のサンプルは、2 つのビジネス エンティティを含む 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.sqlxads_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

次のステップ