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

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

アサーションについて

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

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

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

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

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

テーブルの config ブロックに組み込みアサーションを追加します。

組み込みアサーションをテーブルの config ブロックに追加して、その条件を指定できます。
別の SQLX ファイルに手動アサーションを追加します。

高度なユースケースの場合や Dataform で作成されていないデータセットの場合は、別の SQLX ファイルにカスタムアサーションを手動で記述します。

始める前に

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

[Dataform] ページに移動
リポジトリを作成または選択します。
開発ワークスペースを作成または選択します。
テーブルを定義します。

必要なロール

アサーションの作成に必要な権限を取得するには、ワークスペースに対する 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 ブロックにアサーションを追加する手順は次のとおりです。

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

次のコードサンプルは、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 ファイルに手動アサーションを追加する手順は次のとおりです。

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

ファイル名には数字、英字、ハイフン、アンダースコアのみを使用できます。
[ファイルを作成] をクリックします。
[ファイル] パネルで、新しいファイルをクリックします。
ファイルに次のように入力します。
```
config {
  type: "assertion"
}
```
config ブロックの下には、1 つまたは複数の SQL クエリを記述します。
省略可: [書式] をクリックします。

次のコードサンプルは、フィールド A、B、c が sometable で NULL ではないことをアサートする 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 の選択したアサーションのみに依存させる場合、これらの選択したアサーションをアクション 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

dependOnDependencyAssertions パラメータと includeDependentAssertions パラメータを 1 つのファイルに設定すると、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: [ "" ] に追加します。

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

開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
ワークフローアクションの SQLX ファイルを選択します。
アクションファイルの config ブロックに「dependencies: [ "" ]」と入力します。
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: 手動アサーションの名前。
編集したテーブルに別のアサーションを依存関係として追加するには、ステップ 4 を繰り返します。
省略可: [書式] をクリックします。

次のコードサンプルは、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 です。

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

開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
ワークフローアクションの SQLX ファイルを選択します。
次のいずれかの方法により、ファイルで 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: 編集したアクションの依存関係として設定するアサーションの依存関係アクションの名前。
省略可: [書式] をクリックします。

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

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

開発ワークスペースの [ファイル] ペインで definitions/ を展開します。
ワークフローアクションの SQLX ファイルを選択します。
このファイルで、次の形式で dependOnDependencyAssertions パラメータを true に設定します。
```
config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}
```
ACTION_TYPE は、ワークフローアクションのタイプに置き換えます。サポートされている値には、table、view、operations があります。
省略可: [書式] をクリックします。

次のコードサンプルは、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 に自動追加します。

次のステップ

アサーションタイプの詳細については、Dataform API をご覧ください。
JavaScript を使用してアサーションを定義する方法については、JavaScript を使用した SQL ワークフローの作成をご覧ください。
ワークフローを手動で実行する方法については、実行のトリガーをご覧ください。

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

アサーションについて

始める前に

必要なロール

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

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

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

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

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

`nonNull`

`rowConditions`

`uniqueKey`

`uniqueKeys`

手動アサーション

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

`config` ブロック

`SELECT` ステートメント

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

次のステップ

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

アサーションについて

始める前に

必要なロール

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

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

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

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

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

nonNull

rowConditions

uniqueKey

uniqueKeys

手動アサーション

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

config ブロック

SELECT ステートメント

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

次のステップ

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

`nonNull`

`rowConditions`

`uniqueKey`

`uniqueKeys`

`config` ブロック

`SELECT` ステートメント