本頁面由 Cloud Translation API 翻譯而成。

設定依附元件

本文說明如何在 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 編輯器 (roles/dataform.editor) 身分與存取權管理角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

將依附元件宣告為 `ref` 函式的引數

如要在 SELECT 陳述式中參照並自動宣告依附元件，請將依附元件新增為 ref 函式的引數。

ref 函式是 Dataform 核心內建函式，可讓您參照任何資料表、資料來源宣告或自訂 SQL 作業，並自動依附於這些項目，且工作流程中的 hasOutput 屬性設為 true。

如要進一步瞭解 ref 函式，請參閱Dataform 核心內容方法參考資料。

如要進一步瞭解如何在資料表定義中使用 ref 函式，請參閱「關於資料表定義」。

下列程式碼範例顯示新增的 source_data 資料來源宣告，做為遞增資料表 incremental_table.sqlx SQLX 定義檔案中 ref 函式的引數：

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

將所選動作的斷言設為依附元件

如要只在所選依附項動作的所有直接斷言通過時執行工作流程動作，請在編輯的動作中將 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 的依附元件。

將所有依附動作的判斷結果設為依附元件

如要僅在所有依附動作的所有直接斷言都通過時執行工作流程動作，請在編輯的動作中將 dependOnDependencyAssertions 參數設為 true。Dataform 會在編譯期間，自動將依附項目的直接斷言新增為依附項目。預設值為 false。

在單一檔案中設定 dependOnDependencyAssertions 參數和 includeDependentAssertions 參數時，系統會優先使用 includeDependentAssertions 參數，處理設定該參數的依附元件動作。

如要將所選依附元件動作的所有判斷結果設為依附元件，請按照下列步驟操作：

在開發工作區的「檔案」窗格中，展開 definitions/。
選取工作流程動作 SQLX 檔案。
在檔案中，將 dependOnDependencyAssertions 參數設為 true，格式如下：
```
config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}
```
取代 ACTION_TYPE：工作流程動作的類型。支援的值包括 table、view 和 operations。
選用：按一下「格式」。

下列程式碼範例顯示 sometableE，該程式碼取決於 sometableA、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 的依附元件。

使用覆寫的資料表名稱參照資料表

如要參照覆寫資料表名稱的資料表，請在 ref 函式中，輸入 name: "" 中設定的覆寫資料表名稱。

下列程式碼範例會參照名稱覆寫為 overridden_name 的資料表：

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

如要進一步瞭解如何覆寫資料表名稱，請參閱「覆寫資料表設定」。

後續步驟

如要瞭解如何將斷言設為依附元件，請參閱「測試資料品質」。
如要瞭解如何聲明資料來源，請參閱「聲明資料來源」。
如要瞭解如何定義自訂 SQL 作業，請參閱「建立作業」。
如要瞭解如何透過 include 在工作流程中重複使用程式碼，請參閱「透過 include 在單一存放區中重複使用程式碼」。

設定依附元件

事前準備

必要的角色

將依附元件宣告為 `ref` 函式的引數

在 `config` 區塊中宣告依附元件

將斷言設為依附元件

將所選斷言設為依附元件

`nonNull`

`rowConditions`

`uniqueKey`

`uniqueKeys`

手動聲明著作權

將所選動作的斷言設為依附元件

在 `config` 區塊中

在 `SELECT` 陳述式中

將所有依附動作的判斷結果設為依附元件

使用覆寫的資料表名稱參照資料表

後續步驟

設定依附元件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

將依附元件宣告為 ref 函式的引數

在 config 區塊中宣告依附元件

將斷言設為依附元件

將所選斷言設為依附元件

nonNull

rowConditions

uniqueKey

uniqueKeys

手動聲明著作權

將所選動作的斷言設為依附元件

在 config 區塊中

在 SELECT 陳述式中

將所有依附動作的判斷結果設為依附元件

使用覆寫的資料表名稱參照資料表

後續步驟

設定依附元件

將依附元件宣告為 `ref` 函式的引數

在 `config` 區塊中宣告依附元件

`nonNull`

`rowConditions`

`uniqueKey`

`uniqueKeys`

在 `config` 區塊中

在 `SELECT` 陳述式中