使用断言测试表

本文档介绍了如何使用 Dataform 核心创建 Dataform 表断言并测试工作流代码。

断言简介

断言是一种数据质量测试查询，用于查找违反查询中指定的一个或多个条件的行。如果查询返回任何行，则断言会失败。每次更新 SQL 工作流时，Dataform 都会运行断言，如果任何断言都失败，系统会向您发出提醒。

Dataform 会自动在 BigQuery 中创建包含已编译断言查询结果的视图。如在工作流设置文件中配置的那样，Dataform 会在断言架构中创建这些视图，您可以在其中检查断言结果。

例如，对于默认的 dataform_assertions 架构，Dataform 会以以下格式在 BigQuery 中创建视图：dataform_assertions.assertion_name。

您可以为所有 Dataform 表类型创建断言：表、增量表、视图和物化视图。

您可以通过以下方式创建断言：

准备工作

  1. 在 Google Cloud 控制台中，前往 Dataform 页面。

    前往 Dataform 页面

  2. 选择或创建代码库。

  3. 选择或创建开发工作区。

  4. 创建表。

所需的角色

如需获得创建断言所需的权限，请让您的管理员为您授予工作区的 Dataform Editor (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 表达式，系统会针对每条行条件对每行表格进行评估。如果任何表行导致 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. 在添加文件路径字段中，输入文件的名称，后跟 .sqlx。例如 definitions/custom_assertion.sqlx。

    文件名只能包含数字、字母、连字符和下划线。

  4. 点击创建文件。

  5. 在文件窗格中，点击新文件。

  6. 在该文件中，输入以下内容：

    config {
  type: "assertion"
}

  7. 在 config 代码块下，编写您的 SQL 查询或多个查询。

  8. 可选：点击格式。

以下代码示例展示了 SQLX 文件中的手动断言，该断言断言 sometable 中的字段 A、B 和 c 永远不会为 NULL：

config { type: "assertion" }

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

后续步骤