设置依赖项

本文档介绍了如何在 Dataform 中通过声明依赖关系来定义工作流中对象之间的关系。

您可以定义工作流中对象之间的依赖关系。在依赖关系中，从属对象的执行取决于依赖对象的执行。这意味着，Dataform 会在运行依赖项之后运行被依赖项。您可以通过在依赖对象的 SQLX 定义文件中声明依赖项来定义关系。

依赖项声明构成了工作流的依赖项树，该树决定了 Dataform 运行工作流操作的顺序。

您可以定义以下工作流操作之间的依赖关系：

数据源声明: BigQuery 数据源的声明，可让您在 Dataform 表定义和 SQL 操作中引用这些数据源。您可以将数据源声明设置为依赖项，但不能设置为被依赖项。
Tables: 您在 Dataform 中基于已声明的数据源或工作流中的其他表创建的表。Dataform 支持以下表类型：表、增量表、视图和具体化视图。您可以将某个表设置为依赖项和被依赖项。
自定义 SQL 操作: Dataform 在 BigQuery 中按原样运行的 SQL 语句，无需修改。您可以将 type: operations 文件中定义的自定义 SQL 操作设置为依赖项和被依赖项。如需在 ref 函数中将自定义 SQL 操作声明为依赖项，您需要在自定义 SQL 操作 SQLX 定义文件中将 hasOutput 属性设置为 true。
断言: 可用于测试表数据的数据质量测试查询。 Dataform 每次更新工作流时都会运行断言，并在任何断言失败时提醒您。您可以通过在 config 代码块中声明依赖项，将 type: assertion 文件中定义的断言设置为依赖项和被依赖项。

您可以通过以下方式定义依赖关系：

使用 Dataform 核心 ref 函数在 SELECT 语句中引用依赖项，以声明依赖项。
在 SQLX 定义文件的 config 代码块中声明依赖项列表。

准备工作

在代码库中创建并初始化开发工作区。
可选：声明数据源。
创建至少两个工作流操作：表格、断言、数据源声明或操作。

所需的角色

如需获得为表、断言、数据源声明和自定义 SQL 操作声明依赖项所需的权限，请让您的管理员为您授予工作区的 Dataform Editor (roles/dataform.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

将依赖项声明为 `ref` 函数的实参

如需在 SELECT 语句中引用并自动声明依赖项，请将依赖项添加为 ref 函数的实参。

ref 函数是 Dataform 核心内置函数，可让您引用并自动依赖于工作流中 hasOutput 属性设置为 true 的任何表、数据源声明或自定义 SQL 操作。

如需详细了解 ref 函数，请参阅 Dataform 核心上下文方法参考文档。

如需详细了解如何在表定义中使用 ref 函数，请参阅关于表定义。

以下代码示例展示了在增量表的 incremental_table.sqlx SQLX 定义文件中，作为 ref 函数的实参添加的 source_data 数据源声明：

// filename is incremental_table.sqlx

config { type: "incremental" }

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

在上述代码示例中，source_data 会自动声明为 incremental_table 的依赖项。

以下代码示例展示了 some_table 表定义 SQLX 文件，该文件已作为断言的 custom_assertion.sqlx SQLX 定义文件中 ref 函数的参数添加：

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

在上述代码示例中，some_table 会自动声明为 custom_assertion 的依赖项。在执行期间，Dataform 会先运行 some_table，然后在创建 some_table 后运行 custom_assertion。

在 `config` 代码块中声明依赖项

如需声明在依赖项的 SQL 语句定义中未引用但需要在表、断言或自定义 SQL 操作之前运行的依赖项，请按照以下步骤操作：

在开发工作区的文件窗格中，展开 definitions/ 目录。
选择要修改的表、断言或自定义 SQL 操作 SQLX 文件。
在文件的 config 代码块中，输入以下代码段：
```
dependencies: [ "DEPENDENCY", ]
```
将 DEPENDENCY 替换为字符串目标，例如要添加为依赖项的操作的文件名。您可以输入多个目标，以英文逗号分隔。
可选：点击格式。

以下代码示例展示了 some_table 表和 some_assertion 断言，它们作为依赖项添加到表定义文件的 config 代码块中：

config { dependencies: [ "some_table", "some_assertion" ] }

将断言设置为依赖项

当工作流操作 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 参数，系统会优先使用 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。如果断言中仅定义了一个键数组，则索引为 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：手动断言的名称。
如需向修改后的表格添加另一个断言作为依赖项，请重复执行第 4 步。
可选：点击格式。

以下代码示例展示了添加到表 A 的断言，该表在 dataform 数据集中定义：

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 ...

将所选操作的断言设置为依赖项

如需仅在所选依赖项操作的所有直接断言都通过时运行 Workflows 操作，请在修改后的操作中将 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：包含您要设置为已编辑操作的依赖项的断言的依赖项操作的名称。
可选：点击格式。

以下代码示例展示了 tableC，它依赖于 viewA、tableB 以及 tableB 的所有断言：

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

在上述代码示例中，Dataform 在编译期间会自动将 tableB 的所有直接断言添加为 tableC 的依赖项。

将所有依赖操作的断言设置为依赖项

如需仅在所有依赖项操作的所有直接断言都通过时运行 Workflows 操作，请在修改后的操作中将 dependOnDependencyAssertions 参数设置为 true。在编译期间，Dataform 会自动将依赖操作的直接断言添加为依赖项。默认值为 false。

如果您在单个文件中同时设置了 dependOnDependencyAssertions 参数和 includeDependentAssertions 参数，则对于设置了 includeDependentAssertions 参数的依赖项操作，系统会优先使用 includeDependentAssertions 参数。

如需将所选依赖项操作的所有断言设置为依赖项，请按以下步骤操作：

在开发工作区的文件窗格中，展开 definitions/。
选择工作流操作 SQLX 文件。
在该文件中，将 dependOnDependencyAssertions 参数设置为 true，格式如下：
```
config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}
```
替换 ACTION_TYPE：工作流操作的类型。支持的值包括 table、view 和 operations。
可选：点击格式。

以下代码示例展示了 sometableE，它依赖于 sometableA、sometableB、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 的依赖项。

引用具有替换表名称的表

如需引用具有替换表名的表，请在 ref 函数中输入在 name: "" 中设置的替换表名。

以下代码示例引用了一个名称被替换为 overridden_name 的表：

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

如需详细了解如何替换表名称，请参阅替换表设置。

后续步骤

如需了解如何将断言设置为依赖项，请参阅测试数据质量。
如需了解如何声明数据源，请参阅声明数据源。
如需了解如何定义自定义 SQL 操作，请参阅创建操作。
如需了解如何通过包含项在工作流中重用代码，请参阅通过包含项在单个代码库中重用代码。

设置依赖项

准备工作

所需的角色

将依赖项声明为 `ref` 函数的实参

在 `config` 代码块中声明依赖项

将断言设置为依赖项

将所选断言设置为依赖项

`nonNull`

`rowConditions`

`uniqueKey`

`uniqueKeys`

手动断言

将所选操作的断言设置为依赖项

在 `config` 块中

在 `SELECT` 语句中

将所有依赖操作的断言设置为依赖项

引用具有替换表名称的表

后续步骤

设置依赖项 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

将依赖项声明为 ref 函数的实参

在 config 代码块中声明依赖项

将断言设置为依赖项

将所选断言设置为依赖项

nonNull

rowConditions

uniqueKey

uniqueKeys

手动断言

将所选操作的断言设置为依赖项

在 config 块中

在 SELECT 语句中

将所有依赖操作的断言设置为依赖项

引用具有替换表名称的表

后续步骤

设置依赖项

将依赖项声明为 `ref` 函数的实参

在 `config` 代码块中声明依赖项

`nonNull`

`rowConditions`

`uniqueKey`

`uniqueKeys`

在 `config` 块中

在 `SELECT` 语句中