Dataform API でコンパイルのオーバーライドを構成する

このドキュメントでは、Dataform API を使用して、コンパイルのオーバーライドを伴うコンパイル結果を作成して実行する方法について説明します。

Dataform API コンパイルのオーバーライドについて

SQL ワークフローを実行するために、Dataform はコードを SQL にコンパイルして、コンパイル結果を作成します。 次に、ワークフロー呼び出し中に、Dataform は BigQuery でコンパイル結果を実行します。

デフォルトでは、Dataform は workflow_settings.yaml ファイルの設定を使用してコンパイル結果を作成します。開発ライフサイクルのさまざまな段階で実行されるデータを分離するには、コンパイルのオーバーライドでデフォルト設定をオーバーライドします。

ターミナルで Dataform API リクエストを渡すと、コンパイルのオーバーライドを伴う単一のコンパイル結果を作成して実行できます。ワークスペースまたは選択した Git Committish のコンパイル結果を作成できます。

コンパイル オーバーライドを使用してコンパイル結果を作成するには、Dataform API の compilationResults.create リクエストを送信する必要があります。リクエストでは、Dataform がコンパイル結果にコンパイルするために、ソース、ワークスペース、または Git Commitish を指定する必要があります。compilationResults.create リクエストの CodeCompilationConfig オブジェクトで、コンパイルのオーバーライドを構成できます。

その後、Dataform API の workflowInvocations.create リクエストで作成されたコンパイル結果を実行します。

Dataform API を使用して、次のコンパイルのオーバーライドを構成できます。

Google Cloud プロジェクト: workflow_settings.yaml に defaultProject として設定されたコンパイル結果を Dataform が実行する Google Cloud プロジェクト。

テーブルの接頭辞
コンパイルの結果のすべてのテーブル名に追加されるカスタム接頭辞。
スキーマの接尾辞
カスタム接尾辞。workflow_settings.yaml 内の defaultDataset、またはテーブルの config ブロック内の schema で定義されるテーブルのスキーマに追加されます。

コンパイル変数の値: コンパイル結果で使用されるコンパイル変数の値。コンパイル変数を使用すると、条件付きでテーブルを実行できます。

1 つのコンパイル結果にのみ使用できる Dataform API のコンパイル オーバーライドの代わりに、Google Cloud コンソールでワークスペースのコンパイル オーバーライドを構成できます。

Dataform でコンパイルのオーバーライドを構成する別の方法については、コード ライフサイクルの概要をご覧ください。

始める前に

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

    Dataform に移動

  2. リポジトリを作成または選択します。

  3. 開発ワークスペースを作成または選択します。

コンパイル結果ソースを設定する

Dataform API compilationResults.create リクエストを発生させるには、コンパイル結果のソースを指定する必要があります。

compilationResults.create リクエストのソースとして、Dataform ワークスペース、Git ブランチ、Git タグ、Git commit SHA を設定できます。

ワークスペースをコンパイル結果ソースとして設定する

  • compilationResults.create リクエストで、選択した Dataform ワークスペースのパスを workspace プロパティに次の形式で入力します。
{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

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

  • PROJECT_NAME は、Google Cloud プロジェクトの名前に置き換えます。
  • LOCATION は、workflow_settings.yaml に設定された Dataform リポジトリの場所に置き換えます。
  • REPOSITORY_NAME は、Dataform リポジトリの名前に置き換えます。
  • WORKSPACE_NAME は、Dataform ワークスペースの名前に置き換えます。

次のコードサンプルは、"sales-test" というワークスペースに設定された compilationResults.create リクエストの workspace プロパティを示します。

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Git Commitish をコンパイル結果ソースとして設定する

  • compilationResults.create リクエストで、選択した Git ブランチ、タグ、または commit SHA を次の形式で gitCommitish プロパティに入力します。

    {
  "gitCommitish": "GIT_COMMITISH"
}

GIT_COMMITISH は、選択した Git ブランチ、Git タグ、またはコンパイル結果の Git commit SHA に置き換えます。

次のコードサンプルは、compilationResults.create リクエストの gitCommitish プロパティが "staging" に設定されていることを示しています。

{
  "gitCommitish": "staging"
}

デフォルトの Google Cloud プロジェクトをオーバーライドする

開発に使用するプロジェクトとは別の Google Cloud プロジェクトにステージング テーブルまたは本番環境テーブルを作成するには、Dataform API の compilationResults.create リクエストで CodeCompilationConfig オブジェクトの別の Google Cloud プロジェクト ID を渡します。

compilationResults.create リクエストで別のデフォルトのプロジェクト ID を渡すと、workflow_settings.yaml ファイル内の構成されたデフォルトの Google Cloud プロジェクト ID がオーバーライドされますが、個々のテーブル内の構成された Google Cloud プロジェクト ID はオーバーライドされません。

  • デフォルトの Google Cloud プロジェクト ID をオーバーライドするには、次の形式で、defaultDatabase プロパティを CodeCompilationConfig オブジェクトの選択した Google Cloud プロジェクト ID に設定します。

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

PROJECT_NAME は、コンパイル結果に設定する Google Cloud プロジェクト ID に置き換えます。

テーブルの接頭辞を追加する

コンパイル結果からテーブルを迅速に識別するには、Dataform API の compilationResults.create リクエストで CodeCompilationConfig オブジェクトのテーブル接尾辞を渡すことで、コンパイル結果のすべてのテーブル名に接頭辞を追加します。

  • テーブルの接頭辞を追加するには、CodeCompilationConfig オブジェクトで次の形式で tablePrefix プロパティを設定します。
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

PREFIX は、追加する接尾辞（_staging など）に置き換えます。たとえば、workflow_settings.yaml の defaultDataset が dataform に設定されている場合、Dataform は dataform_staging スキーマにテーブルを作成します。

スキーマの接尾辞を追加する

開発データ、ステージング データ、本番環境データを分離するには、Dataform API の compilationResults.create リクエストで CodeCompilationConfig オブジェクトにスキーマの接尾辞を渡すことで、コンパイル結果のスキーマに接尾辞を追加します。

  • スキーマの接尾辞を追加するには、CodeCompilationConfig オブジェクトの schemaSuffix プロパティを次の形式で設定します。
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

SUFFIX は、追加する接尾辞（_staging など）に置き換えます。たとえば、workflow_settings.yaml の defaultDataset が dataform に設定されている場合、Dataform は dataform_staging スキーマにテーブルを作成します。

注: CodeCompilationConfig schemaSuffix パラメータは、個々のファイルの config ブロックで構成されているスキーマをオーバーライドします。

選択したファイルをコンパイル変数を使用して条件付きで実行する

選択したテーブルを特定の実行設定でのみ実行するには、実行設定のコンパイル変数を作成してから、Dataform API の compilationResults.createリクエスト で CodeCompilationConfig オブジェクトの値を渡します。

Dataform API を使用して、特定の実行設定で条件付きでテーブルを実行するには、次の手順を行います。

  1. コンパイル変数を作成し、選択したテーブルに追加します。

  2. Dataform API コンパイル リクエストの codeCompilationConfig ブロックに、YOUR_VARIABLE と VALUE の Key-Value ペアを次の形式に設定します。

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

  3. YOUR_VARIABLE は、変数の名前に置き換えます（例: executionSetting）。

  4. VALUE は、選択されたテーブルで設定された when 条件を満たすこのコンパイル結果の変数の値に置き換えます。

次のコードサンプルは、Dataform API コンパイル リクエストに渡される executionSetting 変数を示しています。

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

コンパイルのオーバーライドを使用してコンパイル結果を実行する

  • compilationResults.create リクエストによって作成されたコンパイル結果を実行するには、workflowInvocations.create リクエストで compilationResults.create リクエストによって返されたコンパイル結果 ID を渡します。

次のコードサンプルは、workflowInvocations.create リクエストで渡されるコンパイル結果 ID を示しています。

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

次のステップ