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

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

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

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

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

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

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

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

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

Google Cloud プロジェクト: Dataform がコンパイル結果を実行する Google Cloud プロジェクト。workflow_settings.yaml で defaultProject として設定するか、dataform.json で defaultDatabase として設定します。

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

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

Dataform API のコンパイル オーバーライドは 1 つのコンパイル結果にのみ使用できます。別の方法として、Google Cloud コンソールでワークスペースのコンパイル オーバーライドを構成できます。

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

始める前に

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

    Dataform に移動

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

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

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

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

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

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

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

以下を置き換えます。

  • PROJECT_NAME は、Google Cloud プロジェクトの名前に置き換えます。
  • LOCATION は、ワークフロー設定で設定した 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 に置き換えます。

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

{
  "gitCommitish": "staging"
}

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

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

compilationResults.create リクエストで別のデフォルトのプロジェクト ID を渡すと、ワークフロー設定ファイル内の構成されたデフォルトの 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"
}

次のステップ