Dataform ワークフロー設定を構成する

このページでは、特定のリポジトリの Dataform SQL ワークフローの処理設定を編集する方法について説明します。

設定ファイルを編集してスキーマの名前を変更したり、カスタム コンパイル変数をリポジトリに追加したりする必要が生じることがあります。

リポジトリ設定について

各 Dataform リポジトリには、一意のワークフロー設定ファイルが含まれています。このファイルには、Google Cloud プロジェクト ID と、Dataform が BigQuery にアセットをパブリッシュするスキーマが含まれています。Dataform はデフォルトの設定を使用しますが、設定ファイルを編集してニーズに最も合うようにオーバーライドできます。

Dataform コア 3.0.0 以降、ワークフローの設定はデフォルトで workflow_settings.yaml ファイルに保存されます。以前のバージョンの Dataform コアでは、ワークフローの設定は dataform.json ファイルに保存されます。Dataform コア 3.0 の workflow_settings.yaml ファイルは、dataform.json と下位互換性があります。dataform.json を使用してワークフローの設定を保存することは引き続き可能です。今後の互換性のために、workflow_settings.yaml 形式にリポジトリ ワークフロー設定を移行することをおすすめします。

workflow_settings.yaml の概要

Dataform コア 3.0 で導入された workflow_settings.yaml ファイルは、Dataform ワークフローの設定を YAML 形式で保存します。

次のコードサンプルは、サンプル workflow_settings.yaml ファイルを示しています。

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

上記のコードサンプルでは、Key-Value ペアは次のように記述されています。

• defaultProject: BigQuery Google Cloud プロジェクト ID。
• defaultDataset: Dataform がアセットを作成する BigQuery データセット。デフォルトでは dataform と呼ばれます。
• defaultLocation: デフォルトの BigQuery データセット リージョン。BigQuery データセットのロケーションの詳細については、データセットのロケーションをご覧ください。このロケーションで、Dataform はコードを処理し、実行されたデータを保存します。この処理リージョンは、BigQuery データセットのロケーションと一致する必要がありますが、Dataform リポジトリ リージョンと一致する必要はありません。
• defaultAssertionDataset: Dataform がアサーション結果を含むビューを作成する BigQuery データセット。デフォルトでは dataform_assertions と呼ばれます。

workflow_settings.yaml プロパティの詳細については、GitHub のワークフロー設定の configs リファレンスをご覧ください。

Dataform コードの workflow_settings.yaml で定義されたプロパティには、dataform.projectConfig オブジェクトのプロパティとしてアクセスできます。

workflow_settings.yaml オプションからコードでアクセス可能な dataform.projectConfig オプションへの次のマッピングが適用されます。

• defaultProject => defaultDatabase.
• defaultDataset => defaultSchema.
• defaultAssertionDataset => assertionSchema.
• projectSuffix => databaseSuffix.
• datasetSuffix => schemaSuffix.
• namePrefix => tablePrefix.

次のコードサンプルは、ビューの SELECT ステートメントで参照される dataform.projectConfig オブジェクトを示しています。

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

dataform.json の概要

dataform.json ファイルには、Dataform ワークフロー設定が JSON 形式で保存されます。

次のコードサンプルは、サンプル dataform.json ファイルを示しています。

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

上記のコードサンプルでは、Key-Value ペアは次のように記述されています。

• warehouse: Dataform がアセットを作成する BigQuery へのポインタ。
• defaultDatabase: BigQuery Google Cloud プロジェクト ID。
• defaultSchema: Dataform がアセットを作成する BigQuery データセット。
• defaultLocation: デフォルトの BigQuery データセット リージョン。BigQuery データセットのロケーションの詳細については、データセットのロケーションをご覧ください。このロケーションで、Dataform はコードを処理し、実行されたデータを保存します。この処理リージョンは、BigQuery データセットのロケーションと一致する必要がありますが、Dataform リポジトリ リージョンと一致する必要はありません。
• assertionSchema: Dataform がアサーション結果を含むビューを作成する BigQuery データセット。デフォルトでは dataform_assertions と呼ばれます。

プロジェクト コードで dataform.json で定義されたプロパティには、dataform.projectConfig オブジェクトのプロパティとしてアクセスできます。

始める前に

1. リポジトリを作成する

2. リポジトリで開発ワークスペースを作成して初期化します。

必要なロール

Dataform 設定の構成に必要な権限を取得するには、リポジトリに対する Dataform 管理者（roles/dataform.admin）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

スキーマ名を構成する

スキーマ名を構成するには、workflow_settings.yaml ファイルの defaultDataset プロパティと defaultAssertionSchema プロパティ、または dataform.json ファイルの defaultSchema プロパティと assertionSchema プロパティを編集する必要があります。

スキーマの名前を構成する手順は次のとおりです。

  ...
  defaultDataset: mytables
  ...

{
  ...
  "defaultSchema": "mytables",
  ...
}

カスタム コンパイル変数を作成する

コンパイル変数には、リリース構成または Dataform API リクエストで、コンパイルのオーバーライドを使用して変更できる値が含まれています。

workflow_settings.yaml でコンパイル変数を定義し、選択したテーブルに追加すると、リリース構成または Dataform API コンパイルのオーバーライドで値を変更するを使用して、テーブルを条件付きで実行できます。

コンパイル変数を使用してテーブルを条件付きで実行する方法については、Dataform のコード ライフサイクルの概要をご覧ください。

リポジトリ全体で使用できるコンパイル変数を作成するには、次の操作を行います。

...
vars:
  myVariableName: myVariableValue
...

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

コンパイル変数をテーブルに追加する

SQLX テーブル定義ファイルにコンパイル変数を追加する手順は次のとおりです。

1. Dataform 開発ワークスペースに移動します。
2. [ファイル] ペインで、SQLX テーブル定義ファイルを選択します。

3. ファイルに、次の形式で when 句を入力します。

   ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}
   

   以下を置き換えます。

   • YOUR_VARIABLE: は、変数の名前（executionSetting など）に置き換えます。
   • SET_VALUE は、変数の値（staging など）に置き換えます。
   • CONDITION は、テーブルの実行条件に置き換えます。

次のコードサンプルは、when 句と、ステージング実行設定でデータの 10% を実行する executionSetting 変数を含むテーブル定義 SQLX ファイルを示しています。

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

次のコードサンプルは、when 句と myVariableName 変数を含むビュー定義 SQLX ファイルを示しています。

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

ワークフローの設定を workflow_settings.yaml に移行する

ワークフロー設定ファイルが今後の Dataform コア フレームワーク バージョンと互換性を持つようにするには、ワークフロー設定を dataform.json ファイルから workflow_settings.yaml ファイルに移行する必要があります。

workflow_settings.yaml ファイルは dataform.json ファイルに代わります。

リポジトリに依存関係パッケージが Dataform コアしかない場合は、workflow_settings.yaml ファイルが package.json ファイルに置き換えられます。package.json を workflow_settings.yaml に置き換える方法については、Dataform コアパッケージを管理するをご覧ください。

次の表に、ワークフロー設定プロパティの dataform.json から workflow_settings.yaml へのマッピングを示します。

ワークフローの設定を workflow_settings.yaml に移行する手順は次のとおりです。

1. Google Cloud コンソールの [Dataform] ページに移動します。

   [Dataform] ページに移動

2. リポジトリを選択し、ワークスペースを選択します。

3. [ファイル] ペインで [追加追加]、[ファイルを作成] の順にクリックします。

4. [ファイルパスを追加] フィールドに「workflow_settings.yaml」と入力します。

5. [ファイルを作成] をクリックします。

6. workflow_settings.yaml ファイルに、YAML 形式にマッピングされた dataform.json ファイルの設定を追加します。

7. [ファイル] ペインで、dataform.json の横にある [その他] メニューをクリックし、[削除] をクリックします。

8. dataform.json の削除を確定するには、[削除] をクリックします。

次のコードサンプルは、dataform.json ファイルで定義されたワークフロー設定を示しています。

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

次のコードサンプルは、workflow_settings.yaml に変換した上記の dataform.json ファイルを示しています。

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

次のステップ

• Dataform コアパッケージを workflow_settings.yaml に移行する方法については、Dataform コアパッケージを管理するをご覧ください。

• Dataform プロジェクト設定の詳細については、IProjectConfig リファレンスをご覧ください。