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

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

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

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

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

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

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

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

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

Google Cloud プロジェクト
Dataform がコンパイル結果を実行する Google Cloud プロジェクト。dataform.json は defaultDatabase に設定します。
テーブルの接頭辞
コンパイルの結果のすべてのテーブル名に追加されるカスタム接頭辞。
スキーマの接尾辞
カスタム接尾辞。dataform.json 内の defaultSchema、またはテーブルの 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 は、Dataform リポジトリの場所（dataform.json に設定）に置き換えます。
  • 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 に置き換えます。

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

{
  "gitCommitish": "staging"
}

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

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

compilationResults.create リクエストで別のデフォルトのプロジェクト ID を渡すと、dataform.json ファイル内の構成されたデフォルトの 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 など）に置き換えます。たとえば、dataform.json の defaultSchema が dataform に設定されている場合、Dataform は dataform_staging スキーマにテーブルを作成します。

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

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

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

SUFFIX は、追加する接尾辞（_staging など）に置き換えます。たとえば、dataform.json の defaultSchema が 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"
}

次のステップ