リポジトリを管理する

このドキュメントでは、Dataform で次の操作を行う方法について説明します。

始める前に

  1. リポジトリを作成する
  2. 省略可: リポジトリをサードパーティの Git リポジトリに接続します
  3. リポジトリで開発ワークスペースを作成して初期化します

必要なロール

このドキュメントのタスクを完了するために必要な権限を取得するには、管理者に次の 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

  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": {
      "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

  1. Dataform 開発ワークスペースに移動します。
  2. [ファイル] ペインで、dataform.json ファイルを選択します。
  3. 次のコード スニペットを入力します。

    "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 テーブル定義ファイルにコンパイル変数を追加する手順は次のとおりです。

  1. Dataform 開発ワークスペースに移動します。
  2. [ファイル] ペインで、SQLX テーブル定義ファイルを選択します。
  3. ファイルに、次の形式で when 句を入力します。

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

    次のように置き換えます。

    • 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 ファイルへのワークフロー設定プロパティのマッピングを示します。

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 コアパッケージを管理する

このセクションでは、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 ファイルに移行するには、次の操作を行います。

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

    Dataform に移動

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

  3. [ファイル] ペインで、workflow_settings.yaml ファイルを選択します。

  4. workflow_settings.yaml ファイルに、次の形式で Dataform コアパッケージを追加します。

    dataformCoreVersion: "VERSION"
    
    

    VERSION は、3.0.0 など、最新バージョンの Dataform に置き換えます。

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

  6. dataform.json ファイルの削除を確定するには、[削除] をクリックします。

  7. [パッケージをインストール] をクリックします。

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 コアパッケージを移動する手順は次のとおりです。

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

    Dataform に移動

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

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

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

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

  6. package.json ファイルに、次の形式で Dataform コアパッケージを追加します。

    {
        "dependencies": {
            "@dataform/core": "VERSION"
        }
    }
    

    VERSION は、3.0.0 など、最新バージョンの Dataform に置き換えます。

  7. [パッケージをインストール] をクリックします。

  8. [ファイル] ペインで workflow_settings.yaml を選択します。

  9. workflow_settings.yaml ファイルで、dataformCoreVersion プロパティを削除します。

Dataform コアを更新する

新しいパッケージ バージョンを本番環境にデプロイする前に、必ず非本番環境でテストしてください。

Dataform コア依存関係パッケージを更新する手順は次のとおりです。

  1. GitHub の Dataform リリースページ@dataform/core の最新バージョンを確認します。

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

    Dataform に移動

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

  4. [ファイル] ペインで、package.json ファイルまたは workflow_settings.yaml ファイルを選択します。

    Dataform コア依存関係パッケージが設定される場所は、Dataform コアのバージョンとパッケージの使用方法によって異なります。詳細については、Dataform コアパッケージのロケーションを管理するをご覧ください。

  5. 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 に置き換えます。

  6. [パッケージをインストール] をクリックします。

  7. 変更を commit します。

  8. 変更をリポジトリに push します

次のコードサンプルは、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 から pull
your-branch-name からの最近の変更でワークスペースを更新します。このオプションは、ワークスペースに commit されていないか、push されていない commit された変更がない場合、サードパーティの Git リポジトリに接続されているリポジトリで使用できます。
前回の commit に戻す
ワークスペース内のファイルを、前回の commit の状態に復元します。

変更を pull

開発ワークスペースがリポジトリと同期されていない場合、Dataform には [Pull] オプションが表示されます。リポジトリから開発ワークスペースに変更を pull する手順は次のとおりです。

  1. [Dataform] ページで、リポジトリを選択します。
  2. [開発ワークスペース] タブで、開発ワークスペースを選択します。
  3. 開発ワークスペース ページで、次の操作を行います。
    1. Dataform リポジトリ内の場合は、[デフォルトのブランチから pull] をクリックします。
    2. サードパーティ Git リポジトリに接続されているリポジトリ内の場合は、[your-branch-name から pull] をクリックします。

変更を反映する

開発ワークスペースで変更を加えると、Dataform に [Commit] オプションが表示されます。すべてのローカル変更または選択したファイルを commit できます。

[新規 commit] ダイアログで、commit されていない変更が表示されます。

開発ワークスペースからリポジトリに変更を commit する手順は次のとおりです。

  1. [Dataform] ページで、リポジトリを選択します。
  2. リポジトリ ページで、開発ワークスペースを選択します。
  3. 開発ワークスペース ページで,commit をクリックします。
  4. [新しい commit] ペインで次の操作を行います。

    1. [Add a commit message] フィールドに、コミットの説明を入力します。
    2. commit する変更されたファイルを選択します。

      ファイルを何も選択しない場合、Dataform はすべてのローカル変更を commit します。変更されたファイルは、ファイルの状態、ファイル名、パスでフィルタできます。

    3. [全ての変更を commit] または [X 変更を commit] をクリックします。

      ボタンの名前は、commit するファイルの選択内容によって異なります。

変更を push

変更を commit すると、Dataform に [Push] オプションが表示されます。開発ワークスペースからリポジトリに変更を push する手順は次のとおりです。

  1. [Dataform] ページで、リポジトリを選択します。
  2. リポジトリ ページで、開発ワークスペースを選択します。
  3. 変更を commit します
  4. 開発ワークスペース ページで、次の操作を行います。
    1. Dataform リポジトリ内の場合は、[デフォルトのブランチに push する] をクリックします。
    2. サードパーティの Git リポジトリに接続されているリポジトリ内の場合は、[your-branch-name に push] をクリックします。

commit されていない変更を元に戻す

commit されていない変更を元に戻すには、次の手順に従います。

  1. [Dataform] ページで、リポジトリを選択します。
  2. リポジトリ ページで、開発ワークスペースを選択します。
  3. [ファイル] ペインの上にある [その他] メニューをクリックし、[最後の commit にリバート] を選択します。

マージの競合を解決する

マージの競合は、開発ワークスペースのローカル変更が、リポジトリのデフォルトのトラッキング ブランチに加えられた変更と互換性がない場合に発生することがあります。通常、マージの競合は、複数のユーザーが同じファイルを同時に編集している場合に発生します。

通常、別のユーザーが同じブランチに競合する変更を push した後、ブランチから pull すると、マージの競合が発生します。 影響を受けるファイルを編集して、マージの競合を手動で解決する必要があります。

次のコードサンプルは、SQLX ファイルに表示されるマージ競合を示しています。

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

マージ競合を解決する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで、影響を受けるファイルを選択します。
  2. 選択した変更を加えてファイルを編集します。
  3. 変更を commit します
  4. 省略可: 変更を push します

次のステップ