依存関係を設定する

このドキュメントでは、依存関係を宣言して、Dataform のワークフロー内のオブジェクト間の関係を定義する方法について説明します。

ワークフローのオブジェクト間の依存関係を定義できます。依存関係では、依存オブジェクトの実行は依存関係オブジェクトの実行に依存します。つまり、Dataform は依存関係の後に依存を実行します。依存関係は、依存オブジェクトの SQLX 定義ファイル内で依存関係を宣言することで定義します。

依存関係の宣言は、Dataform がワークフロー アクションを実行する順序を決定するワークフローの依存関係ツリーを構成します。

次のワークフロー アクション間の依存関係を定義できます。

データソースの宣言
Dataform テーブル定義と SQL オペレーションでこれらのデータソースを参照できるようにする BigQuery データソースの宣言。データソース宣言は依存関係として設定できますが、依存として設定することはできません。
テーブル
ワークフロー内で宣言されたデータソースまたは他のテーブルに基づいて Dataform で作成するテーブル。Dataform は、テーブル、増分テーブル、ビュー、マテリアライズド ビューのテーブルタイプをサポートしています。テーブルを依存関係または依存として設定できます。
カスタム SQL オペレーション
Dataform が BigQuery で変更せずに実行する SQL ステートメント。type: operations ファイルで定義されたカスタム SQL オペレーションを依存関係および依存として設定できます。カスタム SQL オペレーションを ref 関数の依存関係として宣言するには、カスタム SQL オペレーション SQLX 定義ファイルで　hasOutput プロパティを true に設定する必要があります。
アサーション
テーブルデータのテストに使用できるデータ品質のテストクエリ。Dataform は、ワークフローを更新するたびにアサーションを実行し、アサーションが失敗した場合にアラートを送信します。type: assertion ファイルで定義されたアサーションを依存関係および依存として設定するには、config ブロックで依存関係を宣言します。

依存関係は、次の方法で定義できます。

始める前に

  1. リポジトリで開発ワークスペースを作成して初期化します。
  2. 省略可: データソースを宣言します。
  3. 少なくとも 2 つのワークフロー アクション（テーブル、アサーション、データソース宣言、またはオペレーション）を作成します。

必要なロール

テーブル、アサーション、データソース宣言、カスタム SQL オペレーションの依存関係を宣言するために必要な権限を取得するには、ワークスペースに対する Dataform 編集者 （roles/dataform.editor）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

依存関係を ref 関数の引数として宣言する

SELECT ステートメントで依存関係を参照して自動的に宣言するには、依存関係を ref 関数の引数として追加します。

ref 関数は、ワークフローで hasOutput プロパティが true に設定されているテーブル、データソース宣言、カスタム SQL オペレーションを参照して自動的に依存関係を設定できる Dataform コアの組み込み関数です。

ref 関数の詳細については、Dataform コア コンテキスト メソッドのリファレンスをご覧ください。

テーブル定義で ref 関数を使用する方法について詳しくは、テーブル定義の概要をご覧ください。

次のコードサンプルは、増分テーブルの incremental_table.sqlx SQLX 定義ファイルで ref 関数の引数として追加された source_data データソース宣言を示しています。

// filename is incremental_table.sqlx

config { type: "incremental" }

SELECT * FROM ${ref("source_data")}

前述のコードサンプルでは、source_data が incremental_table の依存関係として自動的に宣言されています。

次のコードサンプルは、アサーションの custom_assertion.sqlx SQLX 定義ファイルで ref 関数の引数として追加された some_table テーブル定義 SQLX ファイルを示しています。

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

前述のコードサンプルでは、some_table が custom_assertion の依存関係として自動的に宣言されています。実行中、Dataform は最初に some_table を実行し、some_table が作成されると custom_assertion を 1 回実行します。

config ブロックで依存関係を宣言する

依存の SQL ステートメント定義で参照されていないものの、テーブル、アサーション、またはカスタム SQL オペレーションの前に実行する必要がある依存関係を宣言するには、次の手順を行います。

  1. 開発ワークスペースの [ファイル] ペインで definitions/ ディレクトリを開きます。
  2. 編集するテーブル、アサーション、またはカスタム SQL オペレーションの SQLX ファイルを選択します。

  3. ファイルの config ブロックに次のコード スニペットを入力します。

    dependencies: [ "DEPENDENCY", ]

    DEPENDENCY は、文字列ターゲット（依存関係として追加するアクションのファイル名など）に置き換えます。複数のターゲットをカンマで区切って入力できます。

  4. 省略可: [書式] をクリックします。

次のコードサンプルは、テーブル定義ファイルの config ブロックに依存関係として追加される some_table テーブルと some_assertion アサーションを示しています。

config { dependencies: [ "some_table", "some_assertion" ] }

アサーションを依存関係として設定する

ワークフロー アクション B が、アサーションを含むワークフロー アクション A に依存している場合、アクション A のアサーションが失敗しても Dataform によるアクション B の実行がブロックされることはありません。アクション A のアサーションが成功した場合にのみアクション B を実行するには、アクション A のアサーションをアクション B の依存関係として設定する必要があります。

選択したアクションの依存関係としてアサーションを設定するには、次の方法があります。

選択したアサーションを依存関係として設定する

選択したアサーションを依存関係として手動で設定するには、編集したアクションの config ブロックの dependencies: [ "" ] 行に追加します。

たとえば、アクション B がアクション A に依存しており、アクション B をアクション A の選択したアサーションのみに依存させる場合、これらの選択したアサーションをアクション B の config ブロックに追加できます。

データソース宣言を除くすべてのアクション タイプについて、選択したアサーションを依存関係として手動で設定できます。

選択した依存関係アクションのアサーションを依存関係として設定する

includeDependentAssertions パラメータを設定すると、選択した依存関係ワークフロー アクションのすべての直接的なアサーションを編集したアクションの依存関係として自動設定できます。Dataform は、各アクションのコンパイル時にこれらのアサーションを依存関係として追加し、依存関係アクションのアサーションの変更があった場合に依存関係が最新版となるようにします。

たとえば、アクション C が アクション A とアクション B に依存し、アクション C のみをアクション A のアサーションに依存させる場合、アクション C を編集して includeDependentAssertions パラメータを設定することで、すべてのアクション A のアサーションをアクション C の依存関係として自動設定できます。

includeDependentAssertions パラメータは、次のタイプのアクションに設定できます。

  • table
  • view
  • operations
すべての依存関係アクションのアサーションを依存関係として設定する

dependOnDependencyAssertions パラメータを設定すると、編集済みアクションのすべての依存関係アクションからの直接的な全アサーションを、編集されたアクションの追加依存関係として自動設定できます。Dataform は、各アクションのコンパイル時にこれらのアサーションを依存関係として追加し、依存関係アクションのアサーションの変更があった場合に依存関係が最新版となるようにします。

たとえば、アクション C がアクション A とアクション B に依存している場合、アクション C を編集して dependOnDependencyAssertions パラメータを設定することで、アクション A とアクション B のすべてのアサーションをアクション C の依存関係として自動設定できます。

dependOnDependencyAssertions パラメータは、次のタイプのアクションに設定できます。

  • table
  • view
  • operations

1 つのファイルで dependOnDependencyAssertions パラメータと includeDependentAssertions パラメータを設定すると、includeDependentAssertions パラメータが優先されます。たとえば、dependOnDependencyAssertions を true に設定しても、選択した依存関係アクションで includeDependentAssertions を false に設定した場合、Dataform はそのアクションのアサーションを依存関係に追加しません。

次のコードサンプルは、同じテーブル定義ファイルに設定された dependOnDependencyAssertions パラメータと includeDependentAssertions パラメータを示しています。

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

上記のコードサンプルでは、Dataform はコンパイル中に actionA と actionC のすべての直接的なアサーションを tableName の依存関係に追加します。

選択したアサーションを依存関係として設定する

選択したアサーションが成功した場合にのみワークフロー アクションを実行するには、編集したアクションの config ブロックの dependencies: [ "" ] 行に選択したアサーションを追加します。

選択したアサーションを選択したワークフロー アクションの依存関係として設定する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
  2. ワークフロー アクションの SQLX ファイルを選択します。
  3. アクション ファイルの config ブロックに「dependencies: [ "" ]」と入力します。

  4. dependencies: [ "" ] 内に、依存関係として設定するアクション アサーションの名前または手動アサーションのファイル名を次のいずれかの形式で入力します。

    nonNull

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • ACTION_DATASET_NAME: アクションが定義されているデータセットの名前。デフォルトのデータセットは、ワークフロー設定ファイルで定義されています。
    • ACTION_NAME: アサーションが定義されているアクションの名前。

    rowConditions

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • DATASET_NAME: アクションが定義されているデータセットの名前。デフォルトのデータセットは、ワークフロー設定ファイルで定義されています。
    • ACTION_NAME: アサーションが定義されているアクションの名前。

    uniqueKey

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • DATASET_NAME: テーブルが定義されているデータセットの名前。デフォルトのデータセットは、ワークフロー設定ファイルで定義されています。
    • ACTION_NAME: アサーションが定義されているテーブルの名前。
    • INDEX: 依存関係として追加する uniqueKey アサーションで定義されたキーの配列のインデックス（例: 0 または 1）。アサーションで定義されたキーの配列が 1 つだけの場合、インデックスは 0 です。

    uniqueKeys

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • DATASET_NAME: テーブルが定義されているデータセットの名前。デフォルトのデータセットは、ワークフロー設定ファイルで定義されています。
    • ACTION_NAME: アサーションが定義されているテーブルの名前。
    • INDEX: 依存関係として追加する uniqueKeys アサーションで定義されたキーの配列のインデックス（例: 0 または 1）。アサーションで定義されたキーの配列が 1 つだけの場合、インデックスは 0 です。

    手動アサーション

    config {
  type: "ACTION_TYPE",
  dependencies: [ "MANUAL_ASSERTION_NAME"]
}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • MANUAL_ASSERTION_NAME 手動アサーションの名前。

  5. 編集したテーブルに別のアサーションを依存関係として追加するには、手順 4 を繰り返します。

  6. 省略可: [書式] をクリックします。

次のコードサンプルは、dataform データセットで定義されているテーブル A に追加されたアサーションを示しています。

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}

次のコードサンプルは、テーブル B に依存関係として追加されたテーブル A のアサーションを示しています。

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

次のコードサンプルは、依存関係としてビューに追加される manualAssertion.sqlx ファイルで定義された手動アサーションを示しています。

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

次のコードサンプルは、manual_assertion ファイルと、依存関係としてテーブルに追加される sometable テーブルのアサーションを示しています。

config {
  type: "table",
  dependencies: [ "manual_assertion",  "dataform_sometable_assertions_nonNull" ,  "dataform_sometable_assertions_rowConditions"]
}

SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...

選択したアクションのアサーションを依存関係として設定する

選択した依存関係アクションのすべての直接的なアサーションが成功した場合にのみワークフロー アクションを実行するには、編集されたアクションで includeDependentAssertions パラメータを true に設定します。Dataform は、コンパイル時に、選択した依存関係アクションの直接的なアサーションを依存関係に自動追加します。デフォルト値は false です。

選択した依存関係アクションのすべてのアサーションを依存関係として設定する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
  2. ワークフロー アクションの SQLX ファイルを選択します。

  3. 次のいずれかの方法により、ファイルで includeDependentAssertions パラメータを true に設定します。

    config ブロック

    config {
type: "ACTION_TYPE",
dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • DEPENDENCY_ACTION_NAME: 編集したアクションの依存関係として設定するアサーションを含む依存関係アクションの名前。

    SELECT ステートメント

      config { type: "ACTION_TYPE" }

  SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}

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

    • ACTION_TYPE: ワークフロー アクションのタイプ（table、view、operations のいずれか）。
    • DEPENDENCY_ACTION_NAME: 編集したアクションの依存関係として設定するアサーションを含む依存関係アクションの名前。

  4. 省略可: [書式] をクリックします。

次のコードサンプルは、viewA、tableB、tableB のすべてのアサーションに依存する tableC を示しています。

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

上記のコードサンプルでは、Dataform はコンパイル中に tableB のすべての直接的なアサーションを依存関係として tableC に自動追加します。

すべての依存関係アクションのアサーションを依存関係として設定する

すべての依存関係アクションの直接的な全アサーションが成功した場合にのみワークフロー アクションを実行するには、編集されたアクションで dependOnDependencyAssertions パラメータを true に設定します。Dataform は、コンパイル中に依存関係アクションの直接的なアサーションを依存関係として自動追加します。デフォルト値は false です。

1 つのファイルで dependOnDependencyAssertions パラメータと includeDependentAssertions パラメータを設定すると、includeDependentAssertions パラメータが設定されている依存関係アクションでは、includeDependentAssertions パラメータが優先されます。

選択した依存関係アクションのすべてのアサーションを依存関係として設定する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
  2. ワークフロー アクションの SQLX ファイルを選択します。

  3. ファイルで、次の形式で dependOnDependencyAssertions パラメータを true に設定します。

    config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}

    ACTION_TYPE は、ワークフロー アクションのタイプに置き換えます。サポートされている値には、table、view、operations があります。

  4. 省略可: [書式] をクリックします。

次のコードサンプルは、sometableA、sometabletableB、sometableC、sometableD に依存する sometableE と、依存関係テーブルのすべての直接的なアサーションを示しています。

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

上記のコードサンプルでは、Dataform はコンパイル中に sometableA、sometableB、sometableC、sometableD のすべての直接的なアサーションを依存関係として sometableE に自動追加します。

オーバーライドされたテーブル名を持つテーブルを参照する

  • オーバーライドされたテーブル名を持つテーブルを参照するには、ref 関数で、name: "" で設定されたオーバーライドされたテーブル名を入力します。

次のコードサンプルは、名前が overridden_name にオーバーライドされたテーブルを参照しています。

  SELECT * FROM ${ref("overridden_name")}

テーブル名のオーバーライドの詳細については、テーブル設定をオーバーライドするをご覧ください。

次のステップ