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

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

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

リポジトリ設定について

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

Dataform core 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 core 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 のワークフロー設定の構成リファレンスをご覧ください。

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 プロパティを編集する必要があります。

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

workflow_settings.yaml

1. 開発ワークスペースの [ファイル] ペインで、workflow_settings.yaml ファイルをクリックします。

2. defaultDataset、defaultAssertionSchema、またはその両方の値を編集します。

次のコードサンプルは、workflow_settings.yaml ファイルで定義されたカスタム defaultDataset 名を示しています。

  ...
  defaultDataset: mytables
  ...

dataform.json

1. 開発ワークスペースの [ファイル] ペインで dataform.json ファイルをクリックします。

2. defaultSchema、assertionSchema、またはその両方の値を編集します。

次のコードサンプルは、dataform.json ファイルで定義されたカスタム defaultSchema 名を示しています。

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

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

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

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

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

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

workflow_settings.yaml

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

3. 次のコード スニペットを入力します。

   "vars": {
     "YOUR_VARIABLE":"VALUE"
   }
   

   以下を置き換えます。

   • YOUR_VARIABLE は、変数の名前に置き換えます。
   • VALUE は、コンパイル変数のデフォルト値に置き換えます。

次のコードサンプルは、workflow_settings.yaml ファイル内で myVariableValue に設定された myVariableName コンパイル変数を示しています。

...
vars:
  myVariableName: myVariableValue
...

次のコードサンプルは、executionSetting コンパイル変数が dev に設定された workflow_settings.yaml ファイルを示しています。

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

dataform.json

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

3. 次のコード スニペットを入力します。

   "vars": {
     "YOUR_VARIABLE":"VALUE"
   }
   

   以下を置き換えます。

   • YOUR_VARIABLE は、変数の名前に置き換えます。
   • VALUE は、コンパイル変数のデフォルト値に置き換えます。

次のコードサンプルは、dataform.json ファイル内で myVariableValue に設定された myVariableName コンパイル変数を示しています。

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

次のコードサンプルは、executionSetting コンパイル変数が dev に設定された dataform.json ファイルを示しています。

{
"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 は、テーブルの実行条件に置き換えます。

次のコードサンプルは、ステージング実行の設定で 10% のデータを実行する when 句と 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 へのマッピングを示します。

dataform.json のプロパティ	workflow_settings.yaml のプロパティ	説明
assertionSchema	defaultAssertionDataset	必須。アサーションのデフォルトのデータセット。
defaultDatabase	defaultProject	必須。デフォルトの Google Cloud プロジェクト名。
defaultLocation	defaultLocation	必須。Dataform がテーブルを作成するデフォルトの BigQuery ロケーション。BigQuery のロケーションの詳細については、データセットのロケーションをご覧ください。
defaultSchema	defaultDataset	必須。デフォルトのデータセット。
databaseSuffix	projectSuffix	省略可。すべての Google Cloud プロジェクト参照に追加する接尾辞。
schemaSuffix	datasetSuffix	省略可。すべてのアクション データセットに追加する接尾辞。
tablePrefix	namePrefix	省略可。すべてのアクション名の先頭に付加する接頭辞。
vars	vars	省略可。コンパイル中にプロジェクト コードで使用できるユーザー定義変数。key: value ペアのリストを含むオブジェクト。
warehouse	-	dataform.json の場合に必須。bigquery に設定してください。 「workflow_settings.yaml」では利用できません。
-	dataformCoreVersion	「dataform.json」では利用できません。新しいリポジトリではデフォルトで workflow_settings.yaml にインストールされます。詳細については、Dataform コア パッケージを管理するをご覧ください。

ワークフローの設定を 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 リファレンスをご覧ください。