このドキュメントでは、Dataform で次の操作を行う方法について説明します。
始める前に
必要なロール
このドキュメントのタスクを完了するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。
-
Dataform の設定を構成し、Dataform コア パッケージのロケーションを管理する: リポジトリの Dataform 管理者 (
roles/dataform.admin
)。 -
Dataform コア パッケージを更新し、Dataform でバージョン管理を使用する: ワークスペースの Dataform 編集者 (
roles/dataform.editor
)
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
Dataform ワークフローの設定を構成する
このセクションでは、特定のリポジトリの Dataform ワークフローの処理設定を編集する方法について説明します。
設定ファイルを編集してスキーマの名前を変更したり、カスタム コンパイル変数をリポジトリに追加したりする必要が生じることがあります。
リポジトリ設定について
各 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 データセット リージョン。このロケーションで、Dataform はコードを処理し、実行されたデータを保存します。この処理リージョンは、BigQuery データセットのロケーションと一致する必要がありますが、Dataform リポジトリ リージョンと一致する必要はありません。BigQuery データセットのロケーションの詳細については、データセットのロケーションをご覧ください。defaultAssertionDataset
: Dataform がアサーション結果を含むビューを作成する BigQuery データセット。デフォルトではdataform_assertions
と呼ばれます。
workflow_settings.yaml
プロパティの詳細については、GitHub の WorkflowSettings をご覧ください。
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 データセット リージョン。このロケーションで、Dataform はコードを処理し、実行されたデータを保存します。この処理リージョンは、BigQuery データセットのロケーションと一致する必要がありますが、Dataform リポジトリ リージョンと一致する必要はありません。BigQuery データセットのロケーションの詳細については、データセットのロケーションをご覧ください。assertionSchema
: Dataform がアサーション結果を含むビューを作成する BigQuery データセット。デフォルトではdataform_assertions
と呼ばれます。
プロジェクト コードの dataform.json
ファイルで定義されたプロパティには、dataform.projectConfig
オブジェクトのプロパティとしてアクセスできます。
スキーマ名を構成する
スキーマ名を構成するには、workflow_settings.yaml
ファイルの defaultDataset
プロパティと defaultAssertionSchema
プロパティ、または dataform.json
ファイルの defaultSchema
プロパティと assertionSchema
プロパティを編集する必要があります。
スキーマの名前を構成する手順は次のとおりです。
workflow_settings.yaml
開発ワークスペースの [ファイル] ペインで、
workflow_settings.yaml
ファイルをクリックします。defaultDataset
またはdefaultAssertionSchema
の値を編集します。
次のコードサンプルは、workflow_settings.yaml
ファイルで定義されたカスタム defaultDataset
名を示しています。
...
defaultDataset: mytables
...
dataform.json
開発ワークスペースの [ファイル] ペインで、
dataform.json
ファイルをクリックします。defaultSchema
またはassertionSchema
の値を編集します。
次のコードサンプルは、dataform.json
ファイルで定義されたカスタム defaultSchema
名を示しています。
{
...
"defaultSchema": "mytables",
...
}
カスタム コンパイル変数を作成する
コンパイル変数には、リリース構成または Dataform API リクエストで、コンパイルのオーバーライドを使用して変更できる値が含まれています。
workflow_settings.yaml
でコンパイル変数を定義し、選択したテーブルに追加すると、リリース構成または Dataform API コンパイルのオーバーライドで値を変更するを使用して、テーブルを条件付きで実行できます。
コンパイル変数を使用してテーブルを条件付きで実行する方法については、Dataform のコード ライフサイクルの概要をご覧ください。
リポジトリ全体で使用できるコンパイル変数を作成するには、次の操作を行います。
workflow_settings.yaml
- Dataform 開発ワークスペースに移動します。
- [ファイル] ペインで、
workflow_settings.yaml
ファイルを選択します。 次のコード スニペットを入力します。
"vars": { "VARIABLE":"VALUE" }
次のように置き換えます。
- 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
- Dataform 開発ワークスペースに移動します。
- [ファイル] ペインで、
dataform.json
ファイルを選択します。 次のコード スニペットを入力します。
"vars": { "VARIABLE":"VALUE" }
次のように置き換えます。
- 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 テーブル定義ファイルにコンパイル変数を追加する手順は次のとおりです。
- Dataform 開発ワークスペースに移動します。
- [ファイル] ペインで、SQLX テーブル定義ファイルを選択します。
ファイルに、次の形式で
when
句を入力します。${when(dataform.projectConfig.vars.VARIABLE === "SET_VALUE", "CONDITION")}
次のように置き換えます。
- VARIABLE: 変数の名前(例:
executionSetting
) - SET_VALUE: 変数の値(例:
staging
) - CONDITION: テーブルの実行条件
- VARIABLE: 変数の名前(例:
次のコードサンプルは、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
ファイルへのワークフロー設定プロパティのマッピングを示します。
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
に移行する手順は次のとおりです。
Google Cloud コンソールの [Dataform] ページに移動します。
リポジトリを選択し、ワークスペースを選択します。
[ファイル] ペインで [追加追加]、[ファイルを作成] の順にクリックします。
[ファイルパスを追加] フィールドに「
workflow_settings.yaml
」と入力します。[ファイルを作成] をクリックします。
workflow_settings.yaml
ファイルに、YAML 形式にマッピングされたdataform.json
ファイルの設定を追加します。[ファイル] ペインで、
dataform.json
の横にある [その他] メニューをクリックし、[削除] をクリックします。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 コアパッケージを管理する
このセクションでは、Dataform コア フレームワークの依存関係パッケージを管理し、最新バージョンに更新する方法について説明します。
Dataform コアは、SQL、SQLX、JavaScript を使用してワークフローを開発するためのオープンソースの Dataform フレームワークです。ベスト プラクティスとして、利用可能な最新バージョンの Dataform コア フレームワークを常に使用することをおすすめします。Dataform コア フレームワークのリリースについては、GitHub の Dataform リリースをご覧ください。
Dataform コアパッケージの場所を管理する
リポジトリで最初のワークスペースを初期化すると、Dataform は Dataform コアを依存関係パッケージとして自動的に設定します。Dataform コア 3.0.0
以降、Dataform はデフォルトで Dataform コアパッケージを workflow_settings.yaml
ファイルにインストールします。以前のバージョンの Dataform コアでは、Dataform コアは package.json
ファイルに設定されていました。
Dataform コア 3.0.0
以降では、リポジトリに Dataform コアのみが含まれている場合は、workflow_settings.yaml
ファイルに設定する必要があります。以前のバージョンの Dataform コアで作成されたリポジトリの場合は、Dataform コアパッケージを workflow_settings.yaml
に移動します。
Dataform に追加のパッケージをインストールするには、package.json
ファイルが必要です。リポジトリで追加のパッケージを使用している場合は、すべてのパッケージが 1 か所に設定されるように、package.json
に Dataform コアパッケージを設定します。リポジトリに package.json
ファイルがない場合は、package.json
ファイルを作成して Dataform コアパッケージを移動して、追加のパッケージをインストールします。
Dataform コアを workflow_settings.yaml
に移動する
3.0.0
より前のバージョンの Dataform コアで作成されたリポジトリで、Dataform コア以外の依存関係パッケージがない場合は、Dataform コアパッケージを package.json
ファイルから workflow_settings.yaml
ファイルに移動し、冗長な package.json
ファイルを削除する必要があります。
Dataform コアパッケージを package.json
ファイルから workflow_settings.yaml
ファイルに移行するには、次の操作を行います。
Google Cloud コンソールの [Dataform] ページに移動します。
リポジトリを選択し、ワークスペースを選択します。
[ファイル] ペインで、
workflow_settings.yaml
ファイルを選択します。workflow_settings.yaml
ファイルに、次の形式で Dataform コアパッケージを追加します。dataformCoreVersion: "VERSION"
VERSION は、
3.0.0
など、最新バージョンの Dataform に置き換えます。[ファイル] ペインで、
package.json
ファイルの横にある [その他] メニューをクリックし、[削除] をクリックします。dataform.json
ファイルの削除を確定するには、[削除] をクリックします。[パッケージをインストール] をクリックします。
Dataform コアを package.json
に移動する
package.json
ファイルは、リポジトリに追加のパッケージをインストールするために必要です。リポジトリで追加のパッケージを使用している場合は、Dataform コアパッケージを含むすべてのパッケージを package.json
ファイルに保存する必要があります。
Dataform コアパッケージが workflow_settings.yaml
ファイルに設定されているためにリポジトリに package.json
ファイルが含まれていない場合は、追加のパッケージをインストールするために package.json
ファイルを作成し、Dataform コアパッケージを workflow_settings.yaml
ファイルから新しく作成された package.json
ファイルに移動する必要があります。
package.json
ファイルを作成して Dataform コアパッケージを移動する手順は次のとおりです。
Google Cloud コンソールの [Dataform] ページに移動します。
リポジトリを選択し、ワークスペースを選択します。
[ファイル] ペインで [追加追加]、[ファイルを作成] の順にクリックします。
[ファイルパスを追加] フィールドに「
package.json
」と入力します。[ファイルを作成] をクリックします。
package.json
ファイルに、次の形式で Dataform コアパッケージを追加します。{ "dependencies": { "@dataform/core": "VERSION" } }
VERSION は、
3.0.0
など、最新バージョンの Dataform に置き換えます。[パッケージをインストール] をクリックします。
[ファイル] ペインで
workflow_settings.yaml
を選択します。workflow_settings.yaml
ファイルで、dataformCoreVersion
プロパティを削除します。
Dataform コアを更新する
新しいパッケージ バージョンを本番環境にデプロイする前に、必ず非本番環境でテストしてください。
Dataform コア依存関係パッケージを更新する手順は次のとおりです。
GitHub の Dataform リリースページで
@dataform/core
の最新バージョンを確認します。Google Cloud コンソールの [Dataform] ページに移動します。
リポジトリを選択し、ワークスペースを選択します。
[ファイル] ペインで、
package.json
ファイルまたはworkflow_settings.yaml
ファイルを選択します。Dataform コア依存関係パッケージが設定される場所は、Dataform コアのバージョンとパッケージの使用方法によって異なります。詳細については、Dataform コアパッケージのロケーションを管理するをご覧ください。
Dataform コア依存関係パッケージを最新バージョンに更新します。
package.json
{ "dependencies": { "@dataform/core": "VERSION" } }
VERSION は、
3.0.0
など、最新バージョンの Dataform に置き換えます。パッケージのインストールに関する問題を回避するには、Dataform コアパッケージのバージョンを明示的に指定します。package.json
ファイルの他のdependencies
オプション(>version
など)は使用しないでください。workflow_settings.yaml
dataformCoreVersion: "VERSION"
VERSION は、
3.0.0
など、最新バージョンの Dataform に置き換えます。[パッケージをインストール] をクリックします。
次のコードサンプルは、package.json
ファイルで @dataform/core
依存関係が 3.0.0
バージョンに更新されたことを示しています。
{
"dependencies": {
"@dataform/core": "3.0.0"
}
}
コードのバージョン管理を行う
このセクションでは、Dataform でバージョン管理を使用して開発状況を管理する方法について説明します。
Dataform は Git を使用して、リポジトリ内のファイルに加えられた変更をそれぞれ追跡します。
Dataform リポジトリでは、Git リポジトリを直接操作します。
接続されたリポジトリでは、リポジトリの接続時に構成したリモート リポジトリのトラッキング ブランチを操作します。
Dataform には、開発ワークスペースの変更のステータスに基づいてバージョン管理オプションが表示されます。たとえば、Dataform は、ワークスペースに commit されていないローカル変更がある場合にのみ、commit オプションを表示します。ワークスペース内のファイルがデフォルト ブランチまたはトラッキング ブランチの正確なコピーである場合、Dataform にはワークスペースが最新というステータスが表示されます。
Dataform には、次のバージョン管理オプションが表示されます。
- X の変更を commit
- ワークスペースまたは選択した変更ファイルのローカル変更の X 番目を commit します。Dataform に commit されていない変更が表示されます。
- デフォルト ブランチに push
- commit した変更をデフォルトのブランチに push します。このオプションは、ワークスペースに commit されていない変更がない場合、Dataform リポジトリで使用できます。
your-branch-name
に push- commit した変更を
your-branch-name
に push します。このオプションは、ワークスペースに commit されていない変更がない場合、サードパーティの Git リポジトリに接続されているリポジトリで使用できます。 - デフォルト ブランチから pull
- デフォルトのブランチからの最近の変更でワークスペースを更新します。 このオプションは、ワークスペースに commit されていないか、push されていない commit された変更がない場合、Dataform リポジトリで使用できます。
your-branch-name
から pullyour-branch-name
からの最近の変更でワークスペースを更新します。このオプションは、ワークスペースに commit されていないか、push されていない commit された変更がない場合、サードパーティの Git リポジトリに接続されているリポジトリで使用できます。- 前回の commit に戻す
- ワークスペース内のファイルを、前回の commit の状態に復元します。
変更を pull
開発ワークスペースがリポジトリと同期されていない場合、Dataform には [Pull] オプションが表示されます。リポジトリから開発ワークスペースに変更を pull する手順は次のとおりです。
- [Dataform] ページで、リポジトリを選択します。
- [開発ワークスペース] タブで、開発ワークスペースを選択します。
- 開発ワークスペース ページで、次の操作を行います。
- Dataform リポジトリ内の場合は、[デフォルトのブランチから pull] をクリックします。
- サードパーティ Git リポジトリに接続されているリポジトリ内の場合は、[
your-branch-name
から pull] をクリックします。
変更を反映する
開発ワークスペースで変更を加えると、Dataform に [Commit] オプションが表示されます。すべてのローカル変更または選択したファイルを commit できます。
[新規 commit] ダイアログで、commit されていない変更が表示されます。
開発ワークスペースからリポジトリに変更を commit する手順は次のとおりです。
- [Dataform] ページで、リポジトリを選択します。
- リポジトリ ページで、開発ワークスペースを選択します。
- 開発ワークスペース ページで,commit をクリックします。
[新しい commit] ペインで次の操作を行います。
- [Add a commit message] フィールドに、コミットの説明を入力します。
commit する変更されたファイルを選択します。
ファイルを何も選択しない場合、Dataform はすべてのローカル変更を commit します。変更されたファイルは、ファイルの状態、ファイル名、パスでフィルタできます。
[全ての変更を commit] または [X 変更を commit] をクリックします。
ボタンの名前は、commit するファイルの選択内容によって異なります。
変更を push
変更を commit すると、Dataform に [Push] オプションが表示されます。開発ワークスペースからリポジトリに変更を push する手順は次のとおりです。
- [Dataform] ページで、リポジトリを選択します。
- リポジトリ ページで、開発ワークスペースを選択します。
- 変更を commit します。
- 開発ワークスペース ページで、次の操作を行います。
- Dataform リポジトリ内の場合は、[デフォルトのブランチに push する] をクリックします。
- サードパーティの Git リポジトリに接続されているリポジトリ内の場合は、[
your-branch-name
に push] をクリックします。
commit されていない変更を元に戻す
commit されていない変更を元に戻すには、次の手順に従います。
- [Dataform] ページで、リポジトリを選択します。
- リポジトリ ページで、開発ワークスペースを選択します。
- [ファイル] ペインの上にある [その他] メニューをクリックし、[最後の commit にリバート] を選択します。
マージの競合を解決する
マージの競合は、開発ワークスペースのローカル変更が、リポジトリのデフォルトのトラッキング ブランチに加えられた変更と互換性がない場合に発生することがあります。通常、マージの競合は、複数のユーザーが同じファイルを同時に編集している場合に発生します。
通常、別のユーザーが同じブランチに競合する変更を push した後、ブランチから pull すると、マージの競合が発生します。 影響を受けるファイルを編集して、マージの競合を手動で解決する必要があります。
次のコードサンプルは、SQLX ファイルに表示されるマージ競合を示しています。
<<<<<<< HEAD
SELECT 1 as CustomerOrders
=======
SELECT 1 as Orders
>>>>>>> refs/heads/main
マージ競合を解決する手順は次のとおりです。
- 開発ワークスペースの [ファイル] ペインで、影響を受けるファイルを選択します。
- 選択した変更を加えてファイルを編集します。
- 変更を commit します。
- 省略可: 変更を push します。
次のステップ
- Dataform プロジェクト設定の詳細については、
IProjectConfig
リファレンスをご覧ください。 - 追加のパッケージをインストールする方法については、Dataform にパッケージをインストールするをご覧ください。
- テーブルの作成方法については、テーブルを作成するをご覧ください。