G-gen の min です。BigQuery のためのデータ変換ワークフローサービスである Dataform における、「ワークスペースコンパイルオーバーライド」「リリース構成」「ワークフロー構成」という3つの機能について解説します。

はじめに

当記事について

BigQuery のためのデータ変換ワークフローサービスである Dataform における、コンパイルと実行のライフサイクル管理について解説します。

具体的には、「ワークスペースコンパイルオーバーライド」「リリース構成」「ワークフロー構成」という3つの機能を用いて、開発環境と本番環境を分離し、実行を自動化する仕組みを詳しく説明します。

Dataform の基本的な概念や使い方については、以下の記事で解説しています。

blog.g-gen.co.jp

Dataform のワークフローライフサイクル

まず、Dataform におけるワークフローのライフサイクルを理解することが重要です。ライフサイクルは、大きく分けて「開発」「コンパイル」「実行」の3つのフェーズで構成されます。

1 開発
Dataform のワークスペースで SQLX ファイルを記述し、データ変換のロジックを開発します。

2 コンパイル
Dataform は、ワークスペースに記述されたコードをリアルタイムで SQL にコンパイルします。このコンパイル結果は、実際に BigQuery で実行される SQL の集合体です。Dataform のコンパイルは密閉されたサンドボックス環境で行われ、毎回同じコードからは同じコンパイル結果が生成される整合性が保証されます。

3 実行
生成されたコンパイル結果を、Dataform が BigQuery 上で実行します。これにより、テーブルやビューが作成・更新されます。

この記事で紹介する機能は、主に「コンパイル」と「実行」のフェーズを、要件に合わせて柔軟にカスタマイズするためのものです。

参考 : Dataform のワークフローライフサイクルの概要

構成機能

Dataform で開発したデータ変換ロジックを実際の環境（開発環境、本番環境など）でどのようにコンパイルして実行するかを規定する一連の流れを「ライフサイクル」と呼びます。このライフサイクルを管理・自動化するために、Dataform では主に以下の3つの機能が提供されています。

これらの機能は、SQLX ファイルを記述するといった「開発」そのものとはレイヤーが異なり、完成したコードを本番環境へ安全にデプロイし、定期実行するための「仕組み」を構築する役割を担います。それぞれの目的と役割は以下のとおりです。

機能名	主な目的	利用フェーズ
ワークスペースコンパイルオーバーライド	開発者ごとの開発環境を分離する	開発（手動）
リリース構成	本番/ステージング用コンパイル結果をテンプレート化する	コンパイル（自動）
ワークフロー構成	コンパイル結果をスケジュール実行する	実行（自動）

これらの機能を組み合わせることで、開発者は個別のサンドボックス環境で開発を進め、完成したコードを Git 経由で本番環境へ安全にデプロイし、定期実行する、といった一連のワークフローを Dataform 内で完結できます。

ワークスペースコンパイルオーバーライド

機能概要

ワークスペースコンパイルオーバーライドは、リポジトリ内のすべてのワークスペースに適用されるコンパイル設定の上書き機能です。主に、開発者ごとに独立した開発環境を分離するために使用します。

この機能を使うと、workflow_settings.yaml（または dataform.json）で定義されたデフォルト設定を、ワークスペースでの手動実行時に限り上書きできます。上書きできる設定は以下の3つです。

Google Cloud プロジェクト
テーブルの接頭辞
スキーマの接尾辞

動的変数を使用できる点が特徴です。例えば、スキーマの接尾辞に ${workspaceName} と設定すると、msasaki という名前のワークスペースで実行した際には、スキーマ名が （デフォルトスキーマ）_msasaki となります。

これにより、各開発者は他の開発者の作業に影響を与えることなく、自分専用のスキーマにテーブルやビューを作成して開発やテストができます。

設定方法

Dataform リポジトリの [設定] > [編集] をクリックします。
[ワークスペースコンパイルオーバーライド] ペインで、プロジェクト ID や接頭辞、接尾辞を設定します。
[保存] をクリックします。

注意点

ワークスペースコンパイルオーバーライドによって生成されたコンパイル結果は、あくまで開発時の手動実行を想定したものです。そのため、このコンパイル結果をスケジュール実行（後述のワークフロー構成）の対象にすることはできません。

参考 : ワークスペースコンパイルのオーバーライドを構成する

リリース構成

機能概要

リリース構成 は、リポジトリのコンパイル結果を作成するための設定をテンプレート化する機能です。本番環境（production）やステージング環境（staging）など、特定の実行環境向けのコンパイル結果を定義するために使用します。

リリース構成では、production や staging といった構成の一意な名前であるリリース IDを定義します。そして、コンパイルの元となる Git のブランチやコミット SHA であるGit Commitishを指定し、コンパイル結果を自動で再作成する頻度を設定します。必要に応じて、Google Cloud プロジェクト ID、テーブルの接頭辞、スキーマの接尾辞などのコンパイルのオーバーライドも設定可能です。

例えば、「main ブランチの最新のコードを元に、1時間ごとに本番環境（production）用のコンパイル結果を自動生成する」といった設定が可能です。ここで生成されたコンパイル結果が、後述するワークフロー構成による定期実行の対象となります。

この仕組みは、CI/CD パイプラインにおける「ビルド」のプロセスに相当します。

設定方法

Dataform リポジトリの [リリースとスケジュール] に移動します。
[製品版リリースの作成]（または、[カスタムリリースの作成]） をクリックします。
リリースID、Git Commitish（ブランチ名など）、頻度、各種オーバーライド設定を入力し、[作成] をクリックします。
参考 : リリース構成を作成する

ワークフロー構成

機能概要

ワークフロー構成 は、リリース構成で作成されたコンパイル結果の実行をスケジュールするための機能です。

ワークフロー構成では、以下の項目を設定します。

リリース構成の選択 : どのリリース構成（例: production）のコンパイル結果を実行するかを選択
実行するアクションの選択 : すべてのアクションを実行するか、特定のタグが付いたアクションのみを実行するかなどを選択
実行スケジュール : 実行頻度（日次、週次など）とタイムゾーン

これにより、「毎日午前3時に、production リリース構成で生成されたコンパイル結果を使って、daily タグが付いたアクションを実行する」といった定期実行を構成できます。

この仕組みは、CI/CD パイプラインにおける「デプロイ」や「ジョブ実行」のプロセスに相当します。リリース構成とワークフロー構成を組み合わせることで、追加のサービス（Cloud Scheduler や Cloud Composer など）を使わずに、Dataform 内で完結した自動実行パイプラインを構築できます。

設定方法

Dataform リポジトリの [リリースとスケジュール] に移動します。
[ワークフロー構成] セクションで [作成] をクリックします。
実行対象のリリース構成、実行するアクション、スケジュールなどを設定し、[作成] をクリックします。
参考 : ワークフロー構成を作成する

開発と管理

ライフサイクルの全体像

ここまで解説した3つの機能を組み合わせた、一般的な開発から本番実行までの流れは以下のとおりです。

1 開発フェーズ（個人のワークスペース）

開発者は、各自のワークスペースで SQLX ファイルを開発・編集します。
ワークスペースコンパイルオーバーライドを利用して、個別のサンドボックス環境（例: msasaki スキーマ）で手動実行し、動作を確認します。

2 リリースフェーズ（Git とリリース構成）

開発が完了したコードを、Git リポジトリの main ブランチ（本番用）や staging ブランチ（ステージング用）にマージします。
リリース構成がスケジュールに従い、main ブランチから本番用のコンパイル結果を、staging ブランチからステージング用のコンパイル結果をそれぞれ自動で作成します。

3 実行フェーズ（ワークフロー構成）

ワークフロー構成が、定義されたスケジュール（例: 毎日午前3時）になると、本番用のリリース構成によって作成された最新のコンパイル結果を BigQuery 上で実行します。

このように、各機能が明確な役割を担うことで、安全で再利用性の高いデータパイプラインのライフサイクル管理が実現されます。

ベストプラクティス

Dataform で開発から本番までのワークフローを管理する際は、環境を分離することがベストプラクティスとされています。

開発環境では、本番データに影響を与えないよう「ワークスペースコンパイルオーバーライド」を活用して、各開発者が個別のスキーマで作業します。

一方、本番環境やステージング環境では、「リリース構成」と「ワークフロー構成」を組み合わせ、Git の特定ブランチを元にしたコンパイルと実行を自動化します。これにより、コードの変更が自動的に本番環境へ反映される、統制の取れたパイプラインを構築できます。

詳細は公式ドキュメントをご参照ください。

参考 : 分離された実行環境のベストプラクティス

必要なロール

Dataform でこれらの構成を管理するには、リポジトリに対して適切な IAM ロールが必要です。

ロール名（ロール ID）	説明
Dataform 管理者（`roles/dataform.admin`）	リリース構成やワークフロー構成の作成・編集・削除などの管理操作に必要

ロールの付与に関する詳細は、公式ドキュメントをご参照ください。

参考 : 必要なロール

リソースの有効期限

Dataform によって作成されるコンパイル結果やワークフローの実行履歴（呼び出し）には、有効期限が設定されています。

ワークフローの呼び出し実行履歴は、90日後に自動で削除されます。

コンパイル結果の有効期限は、その生成方法によって異なります。ワークスペースで開発中に生成されたものは24時間で失効します。リリース構成によって生成されたものは、新しいコンパイル結果が作成されると置き換えられ、最大24時間後に失効します。ワークフロー呼び出しで使われたコンパイル結果は、その呼び出しが有効な期間（最大90日）保持されます。