Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建立資料表

在 Dataform 中，資料表是構成工作流程的物件類型之一。您可以建立資料表，參照為工作流程宣告的資料來源，或工作流程中其他資料表的資料。Dataform 會即時將資料表定義編譯成 SQL。觸發執行作業時，Dataform 會執行 SQL 程式碼，並在 BigQuery 中建立您定義的資料表。

您可以在 type: "table" SQLX 檔案中建立下列資料表類型：

table：一般資料表。
incremental：累加資料表。
view：表格檢視畫面。詳情請參閱「檢視表簡介」。
- materialized：具體化資料表檢視表。詳情請參閱「materialized view 簡介」。

您也可以定義表格分割區和叢集。

如要記錄表格用途或與工作流程中其他表格的關係，可以在表格或所選資料欄中新增說明文件。

如要根據特定條件測試資料表中的資料，您可以建立資料品質測試查詢，稱為「斷言」。Dataform 會在每次更新工作流程時執行斷言，並在斷言失敗時發出快訊。

如要覆寫所選資料表的預設結構定義、資料庫和名稱，可以覆寫資料表設定。

如要停用資料表建立作業，或在建立資料表前後執行 SQL 陳述式，可以設定其他動作。

如要在執行資料表後整理 BigQuery 中的資料表，可以新增 BigQuery 標籤。詳情請參閱「標籤簡介」。

如要在資料表資料欄層級限制資料存取權，您可以新增 BigQuery 政策標記。詳情請參閱「資料欄層級存取控管機制簡介」。

如要保留外部系統在資料表執行期間套用的 BigQuery 資料政策和資料治理標記 (搶先版)，可以保留存取控制中繼資料。

除了在 type: "table" SQLX 檔案中定義資料表，您也可以在 type: "operations" SQLX 檔案中定義自訂 SQL 查詢，藉此建立空白資料表。您可能需要建立空白資料表，以便其他服務在其中填入資料。

事前準備

前往 Google Cloud 控制台的「Dataform」頁面。

前往 Dataform
在存放區中建立及初始化開發工作區。
選用：宣告資料來源。

必要的角色

如要取得完成本文件工作所需的權限，請要求管理員授予您下列 IAM 角色：

工作區的Dataform 編輯者 (roles/dataform.editor)
如要將中繼資料同步至 Knowledge Catalog：專案或 @bigquery 項目群組的 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

如要保留存取控管中繼資料，執行 Dataform 工作流程的服務帳戶必須具備特定 IAM 權限，視工作而定：

擷取中繼資料：如要讀取 INFORMATION_SCHEMA.COLUMNS 檢視區塊，服務帳戶必須具備資料集或資料表結構定義的讀取的權限。下列 IAM 角色都具備這些權限：
- BigQuery 資料檢視者 (roles/bigquery.dataViewer)
- BigQuery 資料編輯者 (roles/bigquery.dataEditor)
- BigQuery 資料擁有者 (roles/bigquery.dataOwner)
- BigQuery 管理員 (roles/bigquery.admin)
套用資料治理標記：如要附加及管理資料表和檢視表的資料治理標記，服務帳戶必須具備 bigquery.tables.createTagBinding 和 bigquery.tables.deleteTagBinding 權限。下列預先定義的 IAM 角色都包含這些權限：
- 標記使用者 (roles/resourcemanager.tagUser)
- 標記管理員 (roles/resourcemanager.tagAdmin)
套用資料政策：如要建立及更新資料政策 (包括無標記政策)，服務帳戶必須具備 bigquery.dataPolicies.create 和 bigquery.dataPolicies.update 權限。下列預先定義的 IAM 角色都包含這些權限：
- BigQuery 資料政策管理員 (roles/bigquerydatapolicy.admin)
- BigQuery 管理員 (roles/bigquery.admin)

建立資料表

本節說明如何在 Dataform 中使用 Dataform Core 建立資料表。

關於資料表定義

如要定義資料表，請定義資料表類型，並在 type: "table" SQLX 檔案中編寫 SELECT 陳述式。接著，Dataform 會將 Dataform 核心程式碼編譯為 SQL、執行 SQL 程式碼，並在 BigQuery 中建立您定義的資料表。

在 Dataform 核心 SELECT 陳述式中，您可以定義資料表結構，並參照工作流程的其他物件。

除了在 type: "table" SQLX 檔案中定義資料表，您也可以在 type: "operations" SQLX 檔案中定義自訂 SQL 查詢，藉此建立空白資料表。詳情請參閱「建立空白資料表」。

使用 `ref` 參照依附元件

如要在 SELECT 陳述式中參照工作流程動作，並自動將其新增為依附元件，請使用 ref 函式。Dataform 會先執行依附元件，再執行依附於這些元件的資料表，以驗證管道順序是否正確。

ref 函式是內建的 Dataform 核心函式，對 Dataform 的依附元件管理至關重要。ref 函式可讓您參照 Dataform 工作流程中定義的下列物件，並自動依附這些物件，而不必硬式編碼結構定義和資料表名稱：

所有支援的資料表類型。
資料來源宣告。
自訂 SQL 作業，並將 hasOutput 屬性設為 true。

Dataform 會使用 ref 函式，建構所有要建立或更新的資料表依附元件樹狀結構。

編譯完成後，Dataform 會在 SQL 陳述式中加入樣板陳述式，例如 CREATE、REPLACE、INSERT 或 MERGE。

下列程式碼範例顯示使用 ref 函式的資料表定義：

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

在 ref 函式中，提供您要依附的資料表或資料來源宣告名稱。這通常是定義該資料表或資料來源宣告的 SQLX 檔案名稱。

如果覆寫資料表名稱，請在 ref 函式中使用覆寫的名稱。舉例來說，您可以將 config { name: "overridden_name" } 的資料表參照為 ref("overridden_name")。詳情請參閱「覆寫資料表設定」和「使用覆寫的資料表名稱參照資料表」。

如果不同結構定義中有多個同名資料表，您可以為 ref 函式提供兩個引數 (結構定義名稱和資料表名稱)，藉此參照特定資料表。

下列程式碼範例顯示 ref 函式，其中包含兩個引數，用於指定特定結構定義中的表格：

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

您也可以手動將資料表依附元件新增至 config 區塊，用於 SELECT 陳述式中 ref 函式未參照的資料表、斷言、資料來源宣告或自訂 SQL 作業。Dataform 會先執行這些依附元件，再執行依附資料表。

下列程式碼範例顯示 config 區塊中的資料表依附元件：

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

如要進一步瞭解工作流程中的依附元件管理，請參閱「設定依附元件」。

使用 `resolve` 參照其他表格

resolve 函式可讓您在 SELECT 陳述式中參照資料表或資料來源宣告，就像 ref 函式一樣，但不會將參照新增為依附元件。也就是說，使用 resolve 函式參照的物件不會影響使用 resolve 函式的資料表執行作業。

如要進一步瞭解內建的 Dataform 核心函式，請參閱「Dataform 核心參考資料」。

建立 SQLX 檔案來定義資料表

將資料表定義 SQLX 檔案儲存在 definitions/ 目錄中。如要在 definitions/ 目錄中建立新的 SQLX 檔案，請按照下列步驟操作：

前往 Google Cloud 控制台的「Dataform」頁面。

前往 Dataform
如要開啟存放區，請按一下存放區名稱。
如要開啟開發工作區，請按一下工作區名稱。
在「Files」(檔案) 窗格中，點按 definitions/ 旁的「更多」。
點選「建立檔案」。
在「Add a file path」(新增檔案路徑) 欄位中，輸入檔案名稱，然後在 definitions/ 後方加上 .sqlx。例如：definitions/my-table.sqlx。

檔案名稱只能包含數字、英文字母、連字號和底線。
點選「建立檔案」。

定義資料表類型

如要建立新的資料表類型定義，請按照下列步驟操作：

在開發工作區的「檔案」窗格中，展開 definitions/ 目錄。
選取要編輯的資料表定義 SQLX 檔案。
在檔案中輸入下列程式碼片段：
```
config { type: "TABLE_TYPE" }
```
將 TABLE_TYPE 替換為下列其中一種資料表類型：
- table
- incremental
- view
選用：如要定義 materialized view，請在 type: "view" 下方，以下列格式輸入 materialized 屬性：
```
config {
  type: "view",
  materialized: true
}
```
詳情請參閱「ITableConfig」。
選用：按一下「格式」。

定義資料表結構和依附元件

如要編寫資料表定義 SELECT 陳述式，並定義資料表結構和依附元件，請按照下列步驟操作：

在開發工作區的「檔案」窗格中，展開 definitions/ 目錄。
選取要編輯的資料表定義 SQLX 檔案。
在 config 區塊下方，編寫 SELECT 陳述式。
選用：按一下「格式」。

下列程式碼範例顯示含有 SELECT 陳述式和 ref 函式的資料表定義：

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

新增手動資料表依附元件

如要新增 SELECT 陳述式中未參照的資料表依附元件，但必須在目前資料表之前執行，請按照下列步驟操作：

在開發工作區的「檔案」窗格中，展開 definitions/ 目錄。
選取要編輯的資料表定義 SQLX 檔案。
在資料表的 config 區塊中，輸入下列程式碼片段：
```
dependencies: [ "DEPENDENCY_TABLE", ]
```
將 DEPENDENCY_TABLE 替換為要新增為依附元件的資料表檔案名稱。您可以輸入多個檔案名稱。
選用：按一下「格式」。

以下程式碼範例顯示新增至資料表定義檔案 config 區塊的兩個資料表，做為手動資料表依附元件：

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

覆寫表格設定

您可以覆寫所選資料表的預設結構定義、資料庫和名稱。

根據預設，資料表會遵循您在 workflow_settings.yaml 中設定的結構定義和資料庫設定。資料表名稱與資料表定義 SQLX 檔案的名稱相同。

如要覆寫所選資料表的結構定義和名稱，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開 definitions/。
開啟 SQLX 資料表定義檔案。
在 config 區塊中，輸入下列程式碼片段：
```
 {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }
```
更改下列內容：
- OVERRIDDEN_SCHEMA：要建立資料表的 BigQuery 資料集。
- OVERRIDDEN_DATABASE：要建立資料表的 BigQuery 專案 ID。
- OVERRIDDEN_NAME：資料表名稱，與 SQLX 資料表定義檔案名稱不同。
選用：按一下「格式」。

詳情請參閱「使用覆寫的資料表名稱參照資料表」。

建立 Apache Iceberg 代管資料表

使用 Dataform 建立 Iceberg 資料表格式的 BigQuery 資料表。這類資料表稱為 Iceberg 代管資料表。如要進一步瞭解必要角色和其他設定工作，請參閱 Iceberg 受管理資料表工作流程的「事前準備」步驟。

建立 Iceberg 資料表定義

如要建立資料表，請在資料表定義檔案的 bigquery 區塊中定義 Iceberg 設定。

如要定義資料表，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開 definitions/。
開啟資料表定義 SQLX 檔案。
在 config 區塊中，新增包含 iceberg 區塊的 bigquery 區塊，格式如下：
```
config {
  type: "table",
  name: "my_table",
  uniqueKey: ["uniquekey"],
  bigquery: {
    iceberg: {
      bucket_name: "BUCKET_NAME"
    }
  }
}
```
將 BUCKET_NAME 替換為儲存資料表資料的 Cloud Storage bucket 名稱。

其他屬性為選用屬性，如未指定，則會使用預設值。詳情請參閱 iceberg 屬性。

您可以提供每個資料表的值，或在 workflow_settings.yaml 中設定工作流程層級的預設值。您可以在 iceberg 區塊中明確設定屬性，覆寫工作流程層級的預設值。

建立資料表分區和叢集

本節說明如何使用 Dataform Core 建立資料表分區和叢集。BigQuery 支援分區資料表和資料表叢集。詳情請參閱「分區資料表簡介」和「建立及使用分群資料表」。

建立資料表分區

如要建立資料表分區，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開 definitions/。
開啟資料表定義 SQLX 檔案。
在 config 區塊中，按照下列格式，在資料表類型宣告下方新增 bigquery 區塊：
```
config {
  type: "table",
  bigquery: {
  }
}
```
在 bigquery 區塊中，輸入下列程式碼片段：
```
    partitionBy: "PARTITION_EXPRESSION"
```
將 PARTITION_EXPRESSION 替換為用於分區資料表的運算式。
選用：按一下「格式」。

下列程式碼範例顯示在資料表定義 SQLX 檔案中，依小時分割資料表：

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

下列程式碼範例說明如何在資料表定義 SQLX 檔案中，依整數值分割資料表：

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

設定分區篩選器

如要設定分區篩選器，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格中，展開 definitions/。
開啟分區資料表定義 SQLX 檔案。
在 bigquery 區塊中，輸入下列程式碼片段：
```
requirePartitionFilter : true
```
選用：按一下「格式」。

下列程式碼範例顯示在分區資料表 SQLX 檔案的 bigquery 區塊中設定的分區篩選器：

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

如要進一步瞭解 BigQuery 的分區篩選器，請參閱「設定分區資料表的必要分區篩選器屬性」。

設定分區的保留期限

如要控管分區資料表中所有分區的保留時間，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格中，展開 definitions/。
開啟分區資料表定義 SQLX 檔案。
在 bigquery 區塊中，輸入下列程式碼片段：
```
partitionExpirationDays: NUMBER_OF_DAYS
```
將 NUMBER_OF_DAYS 替換為要保留分割區的天數。
選用：按一下「格式」。

下列程式碼範例顯示在已分區資料表 SQLX 檔案的 bigquery 區塊中，將分區保留期限設為 14 天：

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

建立資料表叢集

如要建立資料表叢集，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開 definitions/。
開啟資料表定義 SQLX 檔案。
在 bigquery 區塊中，輸入下列程式碼片段：
```
    clusterBy: ["CLUSTER_COLUMN"]
```
將 CLUSTER_COLUMN 替換為要用來分群資料表的資料欄名稱。詳情請參閱 clustering_column_list。
選用：按一下「格式」。

下列程式碼範例顯示依 name 和 revenue 資料欄分群的分區資料表：

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

設定累加型資料表

本節說明如何使用 Dataform 核心設定增量資料表。

關於累加型資料表

Dataform 會根據資料表類型，以不同方式更新資料表。每次執行資料表或檢視區塊時，Dataform 都會從頭重建整個資料表或檢視區塊。

定義累加型資料表時，Dataform 只會在首次建構時從頭開始建構。在後續執行期間，Dataform 只會根據您設定的條件，將新資料列插入或合併至增量資料表。

Dataform 只會將新資料列插入增量資料表中現有的資料欄。如果您變更了累加資料表定義查詢 (例如新增資料欄)，就必須決定是否要從頭重建資料表。如要重建表格，請在下次觸發表格執行時，選取「以完整重新整理執行」選項。如需其他選項，請參閱「變更累加資料表結構定義，而不執行完整重新整理」。

以下是累加資料表的常見用途：

效能最佳化: 對於某些類型的資料 (例如網路記錄或數據分析資料)，您可能只想處理新記錄，而不是重新處理整個資料表。
縮短延遲時間: 您可以運用增量資料表快速但頻繁地執行工作流程，減少輸出資料表的下游延遲。
每日快照: 您可以設定累加資料表，建立資料表資料的每日快照，例如對儲存在正式資料庫中的使用者設定進行縱向分析。

處理累加資料表中的部分資料列

如要決定 Dataform 在每次執行期間處理的資料列子集，請在遞增資料表 SQLX 定義檔案中加入條件式 WHERE 子句。在 WHERE 子句中，您可以指定遞增條件和非遞增條件。執行資料表時，Dataform 會在不全面重新整理的情況下套用累加條件，並在全面重新整理的情況下套用非累加條件。

如要設定累加資料表，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格中，展開 definitions/。
開啟增量資料表定義 SQLX 檔案。
請按照下列格式輸入 WHERE 子句：
```
config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }
```
更改下列內容：
- SELECT_STATEMENT：定義資料表的 SELECT 陳述式。
- INCREMENTAL_CONDITION：您在 WHERE 子句中指定的條件，用於在執行資料表時選取要由 Dataform 處理的資料列，而不需完整重新整理。
- NON_INCREMENTAL_CONDITION：您在 WHERE 子句中指定的條件，用於選取資料列，供 Dataform 在完整重新整理表格時處理。
選用：按一下「格式」。

下列程式碼範例顯示遞增資料表，該資料表會遞增處理 productiondb.logs 資料表的資料列：

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

下列程式碼範例顯示的累加資料表會建立 productiondb.customers 資料表的快照：

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

合併遞增表格中的資料列

如要確認累加資料表只包含一個資料列，且該資料列對應至所選資料欄組合，請將所選資料欄設為 uniqueKey，合併具有相同 uniqueKey 值的資料列。更新資料表時，Dataform 會合併 uniqueKey 值相同的資料列，而不是附加這些資料列。

如要在累加資料表中設定合併功能，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格中，展開 definitions/。
選取遞增資料表定義 SQLX 檔案
在 config 區塊中，使用下列格式將所選資料欄設為 uniqueKey：
```
uniqueKey: ["COLUMN_NAME"]
```
將 COLUMN_NAME 替換為所選資料欄的名稱。
選用：按一下「格式」。

下列程式碼範例顯示一個累加資料表，其中 transaction_id 欄設為 uniqueKey，以驗證該資料表一律包含一個資料列：

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

篩選遞增表格中的資料列

在遞增分區資料表中，如要避免 Dataform 掃描整個資料表來尋找相符的資料列，請設定 updatePartitionFilter，只考慮部分記錄。

下列程式碼範例顯示以 updatePartitionFilter 和 uniqueKey 屬性設定合併作業的遞增式分區資料表，並使用兩種不同的篩選類型：

使用 updatePartitionFilter 屬性進行目標剪除：限制在 MERGE 作業期間掃描目標資料表中的分區，以尋找符合 uniqueKey 的資料列。
使用 WHERE 子句修剪來源：限制在增量執行期間，從來源資料表擷取的資料列。方法是使用 ${when(incremental(), ...)} 函式。

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

從分區資料表擷取資料時，避免掃描整個資料表

建立參照分區資料表的累加型資料表時，建議您建構資料表查詢，避免在每次增量更新期間完整掃描分區資料表。

您可以在資料表查詢中使用常數運算式，限制 BigQuery 掃描的分區數量，藉此更新增量資料表。如要將分區資料表中的值轉換為常數運算式，請使用 BigQuery 指令碼，在 pre_operations 區塊中將該值宣告為變數。接著，在 SELECT 查詢的 WHERE 子句中，將變數做為常數運算式使用。

完成這項設定後，Dataform 會根據參照分區資料表的最新分區更新累加型資料表，不必掃描整個資料表。

如要設定參照分區資料表的累加資料表，並避免全資料表掃描，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格中，展開 definitions/。
選取增量資料表定義 SQLX 檔案
在 pre_operations 區塊中，使用 BigQuery 指令碼宣告變數。
使用參照宣告變數的 WHERE 子句，篩選定義資料表的 SELECT 陳述式。
選用：按一下「格式」。

下列程式碼範例顯示遞增表格，其中參照的 raw_events 表格會依 event_timestamp 分割：

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

在上述程式碼範例中，event_timestamp_checkpoint 變數是在 pre_operations 區塊中定義。event_timestamp_checkpoint 變數隨後會做為 WHERE 子句中的常數運算式。

全面重新整理，從頭重建累加型資料表

如要強制從頭重新建構累加型資料表，請觸發工作流程執行作業，並使用指令列介面搭配 --full-refresh 選項，或使用「Run with full refresh」(執行並全面重新整理) 選項。

在開發工作區或使用 Dataform CLI 選取完整重新整理選項時，Dataform 會在執行期間忽略 ${when(incremental(), ... } 參數，並使用 CREATE OR REPLACE 陳述式重新建立資料表。

防止累加型資料表全面重新整理

為避免從頭重建增量資料表，以及可能遺失資料，您可以將增量資料表設為 protected。如果資料來源是暫時性的，您可能需要防止重建增量資料表。

如要將累加資料表標示為 protected，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開 definitions/。
選取增量資料表定義 SQLX 檔案。
在 config 區塊中輸入 protected: true。
選用：按一下「格式」。

以下程式碼範例顯示標示為 protected 的累加資料表：

config {
  type: "incremental",
  protected: true
}
SELECT ...

變更累加型資料表架構，不全面重新整理

您可以使用 onSchemaChange 設定屬性，在 SELECT 查詢中修改累加資料表結構定義，而不必完整重新整理資料表。這項屬性可讓您在資料表中新增資料欄或移除現有資料欄，同時保留歷來資料。這種方法有助於防止資料遺失，並避免在 BigQuery 中手動更新。

如要使用這項功能，請務必安裝 Dataform Core 3.0.11 以上版本。

設定 onSchemaChange 屬性後，Dataform 會檢查 SELECT 查詢，判斷是否新增或移除資料欄。接著，Dataform 會執行 onSchemaChange 屬性值指定的動作。

如要設定 onSchemaChange 屬性，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開 definitions/。
選取增量資料表定義 SQLX 檔案。
在 config 區塊中，輸入下列程式碼片段：
```
onSchemaChange: "ON_CHANGE_ACTION"
```
將 ON_CHANGE_ACTION 替換為下列其中一項動作：
- IGNORE (預設)：忽略新增的資料欄，並針對缺少的資料欄顯示錯誤。如果未設定 onSchemaChange，則這是結構定義變更時的預設行為。
- FAIL：如果 Dataform 偵測到任何結構定義變更，就會停止動作，有助於維持結構定義一致。
- EXTEND：將查詢中的新資料欄新增至累加資料表，並為先前的記錄新增 NULL 值。如果查詢中的原始結構定義缺少或移除資料欄，就會顯示錯誤。您可以使用這項設定，在執行階段將新資料欄新增至累加資料表。
- SYNCHRONIZE：將查詢中的新資料欄新增至累加資料表，並為先前的記錄新增 NULL 值。移除原始結構定義中存在，但目前查詢中缺少的資料欄。
  
  注意：SYNCHRONIZE 操作無法復原，且使用這個選項移除資料欄時，可能會遺失資料。
  注意：系統不支援刪除已分割和叢集化的資料欄，因為刪除這些資料欄可能會造成負面影響。如果分區或分群資料欄仍遭刪除，系統會使用 ALTER TABLE DROP COLUMN 陳述式處理。Dataform 不會執行檢查或驗證，防止在分區或分群資料欄上執行 ALTER TABLE DROP COLUMN 陳述式。因此，如果捨棄這類資料欄，請務必謹慎處理，並留意可能造成的負面影響。
選用：按一下「格式」。

下列程式碼範例顯示遞增表格，其中 onSchemaChange 屬性已設定 EXTEND 動作：

config {
    type: "incremental",
    onSchemaChange: "EXTEND",
}
SELECT ...

新增資料表說明文件

本節說明如何將資料表、資料欄和記錄的說明新增至 Dataform 核心 SQLX 檔案。

您可以在 Dataform 中為所有類型的資料表 (資料表、遞增資料表和檢視區塊) 新增資料表、資料欄和記錄說明。

建議您記錄下列事項：

資料表的用途。
資料表中資料欄或記錄的內容或角色。
資料表與工作流程其他動作的關係，例如依附於目前資料表的資料表或檢視區塊。
套用至資料表的斷言。
套用至資料表的預先作業或後續作業。
資料表的擁有者，也就是建立資料表的使用者。如果多位團隊成員共同處理工作流程，這項資訊可能會有幫助。

新增 Knowledge Catalog 的中繼資料

BigQuery 的標準中繼資料 (例如資料集、資料表和檢視表) 會自動顯示在 Knowledge Catalog 中。

您也可以直接在 .sqlx 檔案的設定區塊中，為資料表和檢視表定義自訂中繼資料。成功完成動作後，Dataform 會自動啟動中繼資料同步作業，將中繼資料同步至 Knowledge Catalog。這項擴充程序會根據 SQLX 設定中定義的語意中繼資料，更新 Knowledge Catalog。

使用中繼資料索引鍵，指定 Knowledge Catalog 的資訊。擴充程序支援下列中繼資料建構項目：

總覽：項目的說明文件和摘要文字。必須使用 Dataform 核心 3.0.37 以上版本。
一般切面：語意詳細資料，例如資料表系統和類型資訊。必須使用 Dataform Core 3.0.52 以上版本。

以下範例設定說明如何將總覽和一般中繼資料切面新增至 Knowledge Catalog 的資料表設定：

config {
  type: "table",
  metadata: {
    overview: "This table provides standardized trip data.",
    extraProperties: {
        generic: {
              system: "BigQuery",
              type: "table"
        }
      }
  }
}

如要查看中繼資料更新狀態，請參閱檢查工作區執行記錄，瞭解 Dataform 工作流程，或參閱查看過去的手動執行作業，瞭解 BigQuery 管道。

如要驗證同步的中繼資料，可以在 Knowledge Catalog 搜尋資產。詳情請參閱「搜尋資源」。

新增表格說明

如要在 SQLX 檔案中為資料表新增說明，請按照下列步驟操作：

前往 Google Cloud 控制台的「Dataform」頁面。

前往 Dataform
選取存放區。
選取開發工作區。
在「Files」(檔案) 窗格中，點選要編輯的資料表定義 SQLX 檔案。
在檔案的 config 區塊中，以下列格式輸入資料表說明：
```
description: "Description of the table",
```
選用：按一下「格式」。

下列程式碼範例顯示在 SQLX 資料表定義檔案的 config 區塊中，新增資料表說明：

config {
  type: "table",
  description: "Description of the table",
 }

新增資料欄和記錄說明

如要將個別資料欄和記錄的說明新增至 SQLX 檔案，請按照下列步驟操作：

在資料表定義檔案的 config 區塊中，輸入 columns: {}。
在 columns: {} 中，按照下列格式輸入資料欄說明：
```
column_name: "Description of the column",
```

在 columns: {} 中，請按照下列格式輸入記錄說明：

  record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

選用：按一下「格式」。

下列程式碼範例顯示 SQLX 資料表定義檔案 config 區塊中的資料表、資料欄和記錄說明：

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

使用 includes 重複使用資料欄說明文件

您可以使用 JavaScript 包含項目，在 SQL 工作流程中重複使用 Dataform 的資料欄說明。如果 SQL 工作流程中有多個資料欄的名稱和說明相同，建議您重複使用資料欄說明文件。

如要建立可重複使用的資料欄說明，請定義 JavaScript include 常數，並指定資料欄名稱和說明。

您可以定義單一資料欄的說明常數，或定義一組資料欄說明常數，以便重複使用表格中所有資料欄的說明。如要進一步瞭解如何在 Dataform 中建立及使用 include，請參閱「在單一存放區中重複使用 include 中的程式碼」。

以下程式碼範例顯示多個常數，並說明 includes/docs.js JavaScript 檔案中定義的個別資料欄：


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

下列程式碼範例顯示 includes/docs.js 中定義的 user_id 和 age 常數，用於 definitions/my_table.sqlx SQLX 資料表定義檔案，為資料表中的所選資料欄生成說明文件：

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

下列程式碼範例顯示常數，其中包含 includes/docs.js JavaScript 檔案中定義的一組資料欄說明：


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

下列程式碼範例顯示 columns 常數，該常數定義於 includes/table_docs.js，並用於 definitions/my_table.sqlx SQLX 資料表定義檔案，為資料表中的所有欄產生說明文件：

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

新增 BigQuery 標籤

本節說明如何在 Dataform 中為資料表新增標籤。

BigQuery 支援為資源新增標籤。如要進一步瞭解 BigQuery 中的標籤，請參閱「標籤簡介」。

如要在 Dataform 中為資料表新增 BigQuery 標籤，請在資料表定義 SQLX 檔案的 config 區塊中，將標籤新增至 bigquery 區塊。

如要將 BigQuery 標籤新增至資料表定義檔案，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格展開「definitions/」。
選取 SQLX 資料表定義檔案。
在 config 區塊中，按照下列格式新增標籤：
```
bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }
```
更改下列內容：
- LABEL1：標籤名稱
- VALUE_OF_LABEL1：標籤的值
選用：如要新增名稱含有特殊字元的標籤，請在標籤名稱前後加上引號 ("")。
選用：按一下「格式」。

下列程式碼範例顯示新增至已分割資料表定義 SQLX 檔案中 bigquery 區塊的 department:shipping 和 cost-center:logistics 標籤：

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

保留存取控管中繼資料

Dataform 執行會重新建立物件的工作流程動作時 (例如在完整重新整理期間建立標準資料表、檢視表或增量資料表)，通常會在 BigQuery 中產生 CREATE OR REPLACE 陳述式，以更新物件結構定義和資料。在 BigQuery 中，資料表取代作業預設會自動捨棄現有的資料欄層級存取控制中繼資料，例如外部資料治理系統套用的資料政策和資料治理標記 (搶先版)。

您可以設定 Dataform，在工作流程執行期間，自動保留現有的 BigQuery 資料政策 (包括無標記資料政策) 和資料治理標記，只要啟用 preserveGovernanceControls 選項即可。啟用這個選項後，Dataform 會在執行期間依序執行下列動作：

從 INFORMATION_SCHEMA.COLUMNS 檢視表備份現有的資料欄中繼資料。
建立中繼空白暫存資料表。
將安全性政策重新套用至中繼資料表。
在表格中填入資料。
執行原子資料表交換，以取代原始資料表。

啟用資料表的自動化管理保存功能

如要為個別資料表、增量資料表或檢視表啟用資料政策和資料治理標記的自動保留功能，請在物件 SQLX 定義檔案的 config 區塊中，將 preserveGovernanceControls 參數設為 true。

如要為個別表格設定控管保留功能，請按照下列步驟操作：

前往開發工作區。
在「檔案」窗格中，展開 definitions/。
選取 SQLX 資料表定義檔案。
在 config 區塊中輸入 preserveGovernanceControls: true。
選用：按一下「格式」。

下列程式碼範例顯示已啟用控管保留功能的資料表定義：

config {
  type: "table",
  preserveGovernanceControls: true
}

SELECT
  customer_id,
  email,
  phone_number
FROM
  ${ref("raw_customers")}

為所有資料表啟用自動保留控管設定

如要為存放區中的所有資料表、增量資料表和檢視表，啟用自動管理保留功能做為專案層級的預設行為，請在存放區的 workflow_settings.yaml 檔案中，將 preserveGovernanceControls 參數設為 true。

如要設定專案的預設值，請將 preserveGovernanceControls 參數新增至 workflow_settings.yaml 檔案，如下列範例所示：

defaultProject: my-gcp-project-id
defaultDataset: my_dataform_dataset
defaultLocation: US
defaultAssertionDataset: my_dataform_assertions
dataformCoreVersion: 3.0.62
preserveGovernanceControls: true

如果您在 workflow_settings.yaml 檔案中全域啟用管理保留功能，可以覆寫這項行為，並在個別資料表的 config 區塊中將 preserveGovernanceControls 參數設為 false，停用特定資料表的保留功能。

使用後續作業重新套用資料列存取政策

啟用治理保留功能後，系統會自動保護資料欄層級的中繼資料，例如 BigQuery 資料政策和資料治理標記，但不會自動還原資料列存取權政策。由於物件替換會捨棄現有的資料列層級安全性規則，因此您可以在建立資料表後，在 SQLX 資料表定義檔案的 post_operations 區塊中定義 SQL DDL 陳述式，重新套用資料列存取權政策。

下列程式碼範例說明如何在資料表的 post_operations 區塊中重新套用資料列存取權政策：

config {
  type: "table",
}

SELECT
  bike_id,
  start_time,
  duration
FROM
  ${ref("raw_trips")}

post_operations {
  CREATE ROW ACCESS POLICY my_policy
  ON ${self()}
  GRANT TO ('serviceAccount:sa-name@example-gcp-project.iam.gserviceaccount.com')
  FILTER USING (bike_id LIKE 'US-%');
}

限制

使用控管保留功能時，請注意下列限制：

移除結構定義欄。如果從 SQLX 資料表定義中移除資料欄，Dataform 會在還原階段忽略與已刪除資料欄相關聯的所有備份資料政策和標記。
結構定義資料欄重新命名。如果您在 SQLX 資料表定義中重新命名現有資料欄，Dataform 無法將舊標記或政策關聯對應至新的資料欄名稱。因此，這些資料欄的現有標記和政策會遺失或遭到替換，您必須手動將標記和政策重新套用至重新命名的資料欄。
分區和分群變更。如果現有資料表使用 preserveGovernanceControls，則不支援就地變更分區或叢集。BigQuery 會拒絕替換。如要解決這個問題，請捨棄資料表，然後再次執行工作流程。您必須手動將資料欄層級資料政策和資料治理標記，重新套用至重新建立的資料表。
移除過期分區。從設定中移除 partitionExpirationDays 屬性，不會從現有資料表移除分割區到期日。如要從現有資料表移除分區到期時間，必須明確將選項設為所選值，或手動修改資料表。
資料表類型。成功執行後，系統會將資料表回報為資料表副本 (table_type = 'CLONE' 位於 INFORMATION_SCHEMA.TABLES 中)。這個副本的行為與標準資料表相同，且副本中繼資料顯示的基礎資料表已不存在。
資料表層級中繼資料和資料列存取權政策。資料表層級標記和資料列層級存取權政策不會在執行作業之間保留。建立資料表後，您可以在 SQLX 資料表定義檔案的 post_operations 區塊中定義 SQL DDL 陳述式，重新套用資料列存取政策。
非交易式資料表交換。BigQuery DDL 作業不屬於交易性質。如果工作流程執行作業在原子重新命名序列中途失敗，且目標資料表處於中間狀態 (例如資料表永久重新命名為 TABLE_NAME_old 或保留為 df_tmp_intermediate)，則可能需要手動介入。
政策標記。自動化管理保存功能不支援 BigQuery 政策標記。請改為在資料欄中新增 BigQuery 資料治理標記 (預先發布版) 和資料政策，以便使用內建的 SQL 整合功能。

儲存費用注意事項

啟用 preserveGovernanceControls 後，Dataform 會在每次執行時 (或每次完整重新整理累加型資料表時)，透過暫存資料表重新建構資料表。與 BigQuery 中的任何資料表重建作業一樣，資料表的先前版本資料會保留在時間旅行中，保留時間為資料集設定的時間範圍 (預設為七天)，接著是七天的安全防護期。

邏輯儲存空間計費是 BigQuery 的預設計費模式，而實體儲存空間計費則是依資料集設定的選擇性設定。如果資料集採用實體儲存空間計費模式，除了使用中的資料表，系統也會針對保留的時間旅行和防故障資料收費。因此，如果經常重建大型資料表，儲存費用可能會明顯增加。

如要降低這項費用，請採取下列行動：

縮短資料集的時間回溯期至 2 天。
使用累加型資料表，減少全面重建的頻率。
比較資料集的邏輯和實體儲存空間計費方式，確認實體計費方式仍是更具成本效益的選項。

後續步驟

如要瞭解如何使用斷言測試資料表資料，請參閱「測試資料品質」。
如要瞭解如何使用 JavaScript 定義資料表，請參閱「僅使用 JavaScript 建立工作流程」。
如要瞭解如何使用 include 重複使用程式碼，請參閱「使用 include 在單一存放區中重複使用程式碼」。
如要瞭解如何使用 Dataform 指令列介面，請參閱「使用 Dataform CLI」。

建立資料表 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

建立資料表

關於資料表定義

使用 ref 參照依附元件

使用 resolve 參照其他表格

建立 SQLX 檔案來定義資料表

定義資料表類型

定義資料表結構和依附元件

新增手動資料表依附元件

覆寫表格設定

建立 Apache Iceberg 代管資料表

建立 Iceberg 資料表定義

建立資料表分區和叢集

建立資料表分區

設定分區篩選器

設定分區的保留期限

建立資料表叢集

設定累加型資料表

關於累加型資料表

處理累加資料表中的部分資料列

合併遞增表格中的資料列

篩選遞增表格中的資料列

從分區資料表擷取資料時，避免掃描整個資料表

全面重新整理，從頭重建累加型資料表

防止累加型資料表全面重新整理

變更累加型資料表架構，不全面重新整理

新增資料表說明文件

新增 Knowledge Catalog 的中繼資料

新增表格說明

新增資料欄和記錄說明

使用 includes 重複使用資料欄說明文件

新增 BigQuery 標籤

保留存取控管中繼資料

啟用資料表的自動化管理保存功能

為所有資料表啟用自動保留控管設定

使用後續作業重新套用資料列存取政策

限制

儲存費用注意事項

後續步驟

建立資料表

使用 `ref` 參照依附元件

使用 `resolve` 參照其他表格