アサーションを使用してテーブルをテストする

このドキュメントでは、Dataform コアを使用して Dataform テーブルのアサーションを作成し、ワークフロー コードをテストする方法について説明します。

アサーションについて

アサーションは、クエリで指定された 1 つ以上のルールに違反する行を検出するデータ品質テストクエリです。クエリが行を返す場合、アサーションは失敗します。Dataform は、SQL ワークフローを更新するたびにアサーションを実行し、アサーションが失敗した場合にアラートを送信します。

Dataform は、コンパイルされたアサーション クエリの結果を含むビューを BigQuery に自動的に作成します。ワークフロー設定ファイルで構成されているように、Dataform は、アサーションの結果を検査できるアサーション スキーマにこれらのビューを作成します。

たとえば、デフォルトの dataform_assertions スキーマの場合、Dataform は BigQuery に dataform_assertions.assertion_name という形式でビューを作成します。

すべての Dataform テーブルタイプ(テーブル、増分テーブル、ビュー、マテリアライズド ビュー)に対してアサーションを作成できます。

次の方法でアサーション値を作成できます。

始める前に

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

    [Dataform] ページに移動

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

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

  4. テーブルを定義します

必要なロール

アサーションの作成に必要な権限を取得するには、ワークスペースに対する Dataform 編集者roles/dataform.editor)IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

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

組み込みアサーションを作成する

組み込みの Dataform アサーションをテーブルの config ブロックに追加できます。Dataform は、テーブルの作成後にこれらのアサーションを実行します。Dataform がテーブルを公開した後、アサーションを検査できます。

テーブルの config ブロックに、次のアサーションを作成できます。

  • nonNull

    この条件は、指定された列がすべてのテーブル行で null ではないことをアサートします。この条件は、null にならない列に使用されます。

    次のサンプルコードは、テーブルの config ブロックでの nonNull アサーションを示しています。

config {
  type: "table",
  assertions: {
    nonNull: ["user_id", "customer_id", "email"]
  }
}
SELECT ...
  • rowConditions

    この条件は、すべてのテーブル行が定義したカスタム ロジックを満たすことをアサートします。各行の条件はカスタム SQL 式であり、テーブルの各行は各行の条件に対して評価されます。テーブル行が行の条件に違反している場合、アサーションは失敗します。

    次のサンプルコードは、増分テーブルの config ブロック内のカスタム rowConditions アサーションを示しています。

config {
  type: "incremental",
  assertions: {
    rowConditions: [
      'signup_date is null or signup_date > "2022-08-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...
  • uniqueKey

    この条件は、指定した列でテーブル行に同じ値がないことをアサートします。

    次のサンプルコードは、ビューの config ブロックでの uniqueKey アサーションを示しています。

config {
  type: "view",
  assertions: {
    uniqueKey: ["user_id"]
  }
}
SELECT ...
  • uniqueKeys

    この条件は、指定した列でテーブル行に同じ値がないことをアサートします。指定されたすべての列に同じ値を持つ行が複数あると、アサーションは失敗します。

    次のサンプルコードは、テーブルの config ブロックでの uniqueKeys アサーションを示しています。

config {
  type: "table",
  assertions: {
    uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
  }
}
SELECT ...

config ブロックにアサーションを追加する

テーブルの config ブロックにアサーションを追加する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで、テーブル定義 SQLX ファイルを選択します。
  2. テーブル ファイルの config ブロックに「assertions: {}」と入力します。
  3. assertions: {} 内にアサーションを追加します。
  4. 省略可: [書式] をクリックします。

次のコードサンプルは、config ブロックに追加された条件を示しています。

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
    rowConditions: [
      'signup_date is null or signup_date > "2019-01-01"',
      'email like "%@%.%"'
    ]
  }
}
SELECT ...

SQLX を使用して手動アサーションを作成する

手動アサーションは専用の SQLX ファイルに書き込む SQL クエリです。手動アサーション SQL クエリは行を返さないようにする必要があります。クエリの実行時にクエリが行を返すと、アサーションは失敗します。

新しい SQLX ファイルに手動アサーションを追加する手順は次のとおりです。

  1. [ファイル] ペインで、definitions/ の横にある [その他] メニューをクリックします。
  2. [ファイルを作成] をクリックします。
  3. [ファイルパスを追加] フィールドに、ファイルの名前に続けて .sqlx を入力します。例: definitions/custom_assertion.sqlx

    ファイル名 には数字、英字、ハイフン、アンダースコアのみを使用できます。

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

  5. [ファイル] パネルで、新しいファイルをクリックします。

  6. ファイルに次のように入力します。

    config {
      type: "assertion"
    }
    
  7. config ブロックの下には、1 つまたは複数の SQL クエリを記述します。

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

次のコードサンプルは、フィールド ABcsometableNULL ではないことをアサートする SQLX ファイルでの手動アサーションを示しています。

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("sometable")}
WHERE
  a IS NULL
  OR b IS NULL
  OR c IS NULL

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

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

次の方法で、選択したアクションの依存関係としてアサーションを設定できます。

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

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

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

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

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

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

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

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

// filename is tableName.sqlx

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

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

上記のコードサンプルでは、Dataform はコンパイル中に actionAactionC のすべての直接的なアサーションを 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: ワークフロー アクションのタイプ(tableviewoperations のいずれか)。
    • ACTION_DATASET_NAME: アクションが定義されているデータセットの名前。デフォルトのデータセットは、ワークフロー設定ファイルに定義されています
    • ACTION_NAME: アサーションが定義されているアクションの名前。

    rowConditions

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

    以下を置き換えます。

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

    uniqueKey

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

    以下を置き換えます。

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

    手動アサーション

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

    以下を置き換えます。

    • ACTION_TYPE: ワークフロー アクションのタイプ(tableviewoperations のいずれか)。
    • 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: ワークフロー アクションのタイプ(tableviewoperations のいずれか)。
    • DEPENDENCY_ACTION_NAME: 編集したアクションの依存関係として設定するアサーションの依存関係アクションの名前。

    SELECT ステートメント

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

    以下を置き換えます。

    • ACTION_TYPE: ワークフロー アクションのタイプ(tableviewoperations のいずれか)。
    • DEPENDENCY_ACTION_NAME: 編集したアクションの依存関係として設定するアサーションの依存関係アクションの名前。
  4. 省略可: [書式] をクリックします。

次のコードサンプルは、viewAtableB、および 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 パラメータが優先されます。

選択した依存関係アクションのすべてのアサーションを依存関係として設定するには、次の手順を行います。

  1. 開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
  2. ワークフロー アクションの SQLX ファイルを選択します。
  3. このファイルで、次の形式で dependOnDependencyAssertions パラメータを true に設定します。

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

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

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

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

// filename is sometableE.sqlx

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

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

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

次のステップ