使用斷言測試資料表

本文件說明如何使用 Dataform 核心建立 Dataform 資料表斷言，並測試工作流程程式碼。

關於斷言

斷言是資料品質測試查詢，可找出違反查詢中一或多個條件的資料列。如果查詢傳回任何資料列，斷言就會失敗。Dataform 每次更新 SQL 工作流程時都會執行斷言，並在任何斷言失敗時發出快訊。

Dataform 會自動在 BigQuery 中建立檢視表，其中包含已編譯斷言查詢的結果。如工作流程設定檔中所設定，Dataform 會在斷言結構定義中建立這些檢視畫面，讓您檢查斷言結果。

舉例來說，對於預設的 dataform_assertions 結構定義，Dataform 會在 BigQuery 中以以下格式建立檢視畫面：dataform_assertions.assertion_name。

您可以為所有資料表格類型建立斷言：資料表、增量資料表、檢視表和物化檢視表。

您可以透過下列方式建立斷言：

事前準備

  1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

    前往「Dataform」頁面

  2. 選取或建立存放區。

  3. 選取或建立開發工作區。

  4. 建立資料表。

必要的角色

如要取得建立斷言所需的權限，請要求管理員為您授予工作區的 Dataform 編輯者 (roles/dataform.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

建立內建斷言

您可以將內建的資料表單斷言新增至資料表的 config 區塊。Dataform 會在建立資料表後執行這些斷言。Dataform 建立表格後，您可以查看工作區的「工作流程執行記錄」分頁中是否有通過斷言。

您可以在資料表的 config 區塊中建立下列斷言：

  • nonNull

    這個條件會斷言指定的資料欄在所有資料表列中皆非空值。這個條件可用於絕不會為空值的資料欄。

    下列程式碼範例顯示資料表 config 區塊中的 nonNull 斷言：

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

  • rowConditions

    這個條件會斷言所有表格資料列都遵循您定義的自訂邏輯。每個資料列條件都是自訂 SQL 運算式，每個資料列都會根據每個資料列條件進行評估。如果任何資料列的結果為 false，斷言就會失敗。

    下列程式碼範例顯示在增量資料表的 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 區塊中加入斷言

如要將斷言新增至資料表的設定區塊，請按照下列步驟操作：

  1. 在開發工作區的「Files」窗格中，選取資料表定義 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. 在「Add a file path」欄位中，輸入檔案名稱後接 .sqlx。例如：definitions/custom_assertion.sqlx。

    檔案名稱只能包含數字、英文字母、連字號和底線。

  4. 點選「建立檔案」。

  5. 在「Files」窗格中，按一下新檔案。

  6. 在檔案中輸入：

    config {
  type: "assertion"
}

  7. 在 config 區塊下方編寫 SQL 查詢或多個查詢。

  8. 選用步驟：按一下「格式」。

以下程式碼範例顯示 SQLX 檔案中的手動斷言，斷言 A、B 和 c 欄位絕不會在 sometable 中為 NULL：

config { type: "assertion" }

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

後續步驟