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

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

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

リポジトリ設定について

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

Dataform core 3.0 以降、デフォルトではワークフロー設定は workflow_settings.yaml ファイルに保存されます。以前のバージョンの Dataform コアでは、ワークフローの設定は dataform.json ファイルに保存されます。Dataform コア 3.0 の workflow_settings.yaml ファイルは、dataform.json と下位互換性があります。引き続き dataform.json を使用して Dataform を構成できます。

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 データセット。デフォルトでは dataform と呼ばれます。
• 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!"
  )}

次のステップ

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

• Dataform でコードをバージョン管理する方法については、コードのバージョン管理をご覧ください。

• テーブルの定義方法については、テーブルを作成するをご覧ください。