断言简介
断言是一种数据质量测试查询,可查找违反 更多规则。如果查询返回任何行,则断言 失败。Dataform 每次更新 SQL 工作流时都会运行断言 并在断言失败时发出提醒
Dataform 会自动在 BigQuery 中创建包含以下内容的视图: 已编译的断言查询的结果。如 在工作流程设置文件中配置 Dataform 在断言架构中创建这些视图,您可以 并检查断言结果。
例如,对于默认 dataform_assertions
架构,Dataform
按以下格式在 BigQuery 中创建视图:
dataform_assertions.assertion_name
。
您可以为所有 Dataform 表类型创建断言:表、 增量表、视图和具体化视图。
您可以通过以下方式创建断言:
-
您可以向表的
config
代码块添加内置断言,并 指定其条件 -
您可以在单独的 SQLX 文件中手动编写自定义断言,以进行高级 或非 Dataform 创建的数据集。
准备工作
所需的角色
为了获得创建断言所需的权限
请让管理员向您授予
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 表达式,表中的每个行都是 针对每一行条件进行评估。如果有任何表行,则断言失败 不符合任何行条件。
以下代码示例展示了
rowConditions
增量表的config
块:
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 块添加断言,请按以下步骤操作:
- 在开发工作区的 Files 窗格中,选择一个表 定义 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 文件中添加手动断言,请按以下步骤操作:
- 在 Files 窗格中,点击
definitions/
旁边的 More 菜单。 - 点击创建文件。
在添加文件路径字段中,输入文件名,后跟
.sqlx
。例如definitions/custom_assertion.sqlx
。文件名只能包含数字、字母、连字符和下划线。
点击创建文件。
在 Files 窗格中,点击新文件。
在文件中,输入:
config { type: "assertion" }
在
config
代码块下方,编写您的 SQL 查询或多个查询。可选:点击格式。
以下代码示例显示了在 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
将断言设置为依赖项
当工作流操作 B 依赖于包含断言的工作流操作 A 时, 操作 A 的断言失败不会阻止 Dataform 执行 B 操作。要执行 操作 B 仅在操作 A 的断言通过时发出, 您需要将操作 A 的断言设置为操作 B 的依赖项。
你可以将断言设为 操作:
- 将所选断言设置为依赖项
您可以通过添加所选断言,手动将其设为依赖项 更改为已修改操作的
config
代码块中的dependencies: [ "" ]
。例如,如果操作 B 依赖于操作 A, 并且您希望操作 B 仅依赖于所选断言 操作A后,您可以添加这些选定的断言
config
操作块 B。您可以手动将所选断言设置为所有操作的依赖项 (数据源声明除外)。
- 将所选依赖项操作的断言设为依赖项
您可以将
includeDependentAssertions
参数设为自动 将所选依赖项工作流操作的所有直接断言设置为 所修改操作的依赖项。Dataform 会将这些断言添加为 依赖项,以确保依赖项 如果依赖操作的断言发生更改,则保持最新状态。例如,如果操作 C 依赖于操作 A 和 B,则: 但您只希望操作 C 依赖于操作 A 的断言, 您可以修改操作 C 并设置
includeDependentAssertions
参数 自动将操作 A 的所有断言设置为依赖项 C 操作的 intent 过滤器。您可以为操作设置
includeDependentAssertions
参数 以下几类:table
view
operations
- 将所有依赖项操作的断言设置为依赖项
您可以将
dependOnDependencyAssertions
用于自动设置所有依赖项操作的所有直接断言的参数 作为修改操作的其他依赖项。 Dataform 会在每次编译期间将这些断言添加为依赖项 以确保依赖项 如果依赖操作的断言发生更改,则保持最新状态。例如,如果操作 C 依赖于操作 A 和 B,则: 您可以修改操作 C 并设置
dependOnDependencyAssertions
参数 以自动设置操作 A 和 B 的所有断言 操作 C 的依赖项。您可以为操作设置
dependOnDependencyAssertions
参数 以下几类:table
view
operations
设置 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
的依赖项。
将所选断言设为依赖项
要仅在所选断言通过时执行工作流操作,
您可以将选定的断言添加到 dependencies: [ "" ]
在所修改操作的 config
代码块中。
如需将选定的断言设置为所选工作流操作的依赖项,请执行以下操作: 请按以下步骤操作:
- 在开发工作区的 Files 窗格中,展开
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
。如果断言中只定义了一个键数组, 索引为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
。如果断言中只定义了一个键数组, 索引为0
。
手动断言
config { type: "ACTION_TYPE", dependencies: [ "MANUAL_ASSERTION_NAME"] }
替换以下内容:
- ACTION_TYPE:工作流操作的类型:
table
、view
或operations
。 - MANUAL_ASSERTION_NAME 是手动断言的名称。
- ACTION_TYPE:工作流操作的类型:
如需将另一个断言作为依赖项添加到修改的表中, 重复第 4 步。
可选:点击格式。
以下代码示例展示了添加到表 A 中的断言,
在 dataform
数据集内定义的值:
config {
type: "table",
assertions: {
uniqueKey: ["user_id"],
nonNull: ["user_id", "customer_id"],
}
}
以下代码示例显示了作为依赖项添加的表 A 断言 添加到表 B:
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
。
如需将所选依赖项操作的所有断言设为依赖项,请执行以下操作: 请按以下步骤操作:
- 在开发工作区的 Files 窗格中,展开
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:依赖项操作的名称 您想要将哪些断言设置为所修改操作的依赖项。
- ACTION_TYPE:工作流操作的类型:
可选:点击格式。
以下代码示例展示了依赖于 viewA
、tableB
的 tableC
以及 tableB
的所有断言:
// filename is tableC.sqlx
config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}
SELECT * FROM ...
在前面的代码示例中,Dataform 会自动添加所有
将 tableB
的断言作为依赖项直接指向 tableC
。
将所有依赖项操作的断言设置为依赖项
仅当所有直接断言均发生变化时,才执行工作流操作
所有依赖项操作都会通过,
在修改后的操作中将 dependOnDependencyAssertions
参数设为 true
。
Dataform 会自动添加依赖项的直接断言
将操作视为依赖项默认值为 false
。
设置 dependOnDependencyAssertions
参数和
includeDependentAssertions
参数,
对于依赖项,includeDependentAssertions
参数优先
将为其设置该字段。
如需将所选依赖项操作的所有断言设为依赖项,请执行以下操作: 请按以下步骤操作:
- 在开发工作区的 Files 窗格中,展开
definitions/
。 - 选择工作流操作 SQLX 文件。
在文件中,将
dependOnDependencyAssertions
参数设置为true
格式如下:config { type: "ACTION_TYPE", dependOnDependencyAssertions: true, dependencies: [ "dependency1", "dependency2" ] }
替换 ACTION_TYPE:工作流操作的类型。 支持的值包括
table
、view
和operations
。可选:点击格式。
以下代码示例展示了依赖于 sometableA
的 sometableE
,
sometabletableB
、sometableC
和 sometableD
以及
依赖关系表:
// 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 工作流。
- 如需了解如何手动执行工作流,请参阅 触发器执行。