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

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

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

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

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

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

SQL ワークフローの主なステージは 3 つあります。

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

definitions ディレクトリ内のサブディレクトリの次の構造には、SQL ワークフローの主なステージが反映されています。

sources
データソースの宣言とソースデータの基本的な変換（フィルタリングなど）。
intermediate
sources から読み取り、変換されたデータを使用して 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 つのスキーマ内の複数のデータソースを示しており、1 つの JavaScript ファイル内で宣言されています。

[
  "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.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

次のステップ