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」(新增檔案路徑) 欄位中，依序輸入檔案名稱和 .sqlx (位於 definitions/ 後方)。例如：definitions/my-table.sqlx。

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

定義資料表類型

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

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

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

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

在開發工作區的「Files」(檔案) 窗格中，展開 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

緩解資料欄結構定義限制

在 type: "table" 或 type: "incremental" SQLX 檔案中定義資料表時，Dataform 會將 SELECT 查詢編譯為 BigQuery 中的 CREATE OR REPLACE TABLE ... AS SELECT 陳述式，不含明確的資料欄結構定義定義清單。因此，BigQuery 預設會以 NULLABLE 模式建立資料欄。

Dataform 資料表定義不支援在 config 區塊或 columns 屬性中，將資料欄的模式設為 REQUIRED (NOT NULL)。在 BigQuery 中，您也無法將現有資料欄的模式從 NULLABLE 變更為 REQUIRED，除非您使用明確的結構定義定義重新建立資料表。如要進一步瞭解如何在 BigQuery 中修改資料欄模式，請參閱「變更資料欄模式」。

如要驗證非空值，或建立含有 REQUIRED 欄的資料表，請採用下列其中一種方法：

使用斷言驗證非空值: 在資料表的 config 區塊中，新增內建的 nonNull 或 rowConditions 斷言，例如 assertions: { nonNull: ["column_name"] } 或 assertions: { rowConditions: ["column_name IS NOT NULL"] }。您也可以在獨立的 type: "assertion" SQLX 檔案中定義手動斷言。斷言會檢查工作流程執行期間，資料列是否不含 NULL 值，而不會將基礎 BigQuery 資料欄模式從 NULLABLE 變更為 REQUIRED。如要進一步瞭解斷言，請參閱「使用斷言測試資料」。
使用自訂 SQL 作業或在 BigQuery 中定義 NOT NULL 資料欄: 如要建立 BigQuery 結構定義將資料欄設為 REQUIRED 模式的資料表，請在 config { type: "operations", hasOutput: true } 的自訂 SQL 作業檔案中，編寫含有明確 NOT NULL 資料欄限制的 CREATE OR REPLACE TABLE DDL 陳述式，或直接在 BigQuery 中建立及管理資料表結構定義。如要進一步瞭解如何在 DDL 陳述式中定義 REQUIRED 資料欄，請參閱「建立含有 REQUIRED 資料欄的資料表」。

新增手動資料表依附元件

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

在開發工作區的「Files」(檔案) 窗格中，展開 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 核心建立資料表分區和叢集。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 只會將新資料列插入增量資料表中現有的資料欄。如果變更累加表格定義查詢 (例如新增資料欄)，則必須決定是否要從頭重新建立表格。如要重建資料表，請在下次觸發資料表執行作業時，選取「Run with full refresh」(執行並完整重新整理) 選項。如需其他選項，請參閱「變更累加資料表結構定義，而不執行完整重新整理」。

以下是累加表格的一些常見用途：

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

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

如要指定 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 包含常數，並指定資料欄名稱和說明。

您可以定義包含單一資料欄說明的常數，或包含一組資料欄說明的常數，以便重複使用資料表中所有資料欄的說明。如要進一步瞭解如何在 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 標籤新增至資料表定義檔案，請按照下列步驟操作：

前往開發工作區。
在「Files」窗格中，展開「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。

如要設定專案層級的預設值，請在 workflow_settings.yaml 檔案中加入 preserveGovernanceControls 參數，如以下範例所示：

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.')
  FILTER USING (bike_id LIKE 'US-%');
}

限制

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

移除結構定義欄。如果從 SQLX 資料表定義中移除資料欄，Dataform 會在還原階段忽略與已刪除資料欄相關聯的所有備份資料政策和標記。
結構定義資料欄重新命名。如果您在 SQLX 資料表定義中重新命名現有資料欄，Dataform 無法將舊標記或政策關聯對應至新的資料欄名稱。因此，這些資料欄上的現有標記和政策會遺失或互換，您必須手動將標記和政策重新套用至重新命名的資料欄。
分區和分群變更。不支援就地變更使用 preserveGovernanceControls 的現有資料表分區或分群。BigQuery 會拒絕替換。如要解決這個問題，請捨棄資料表，然後再次執行工作流程。您必須手動將資料欄層級資料政策和資料治理標記，重新套用至重新建立的資料表。
移除分區到期時間。從設定中移除 partitionExpirationDays 屬性，並不會從現有資料表中移除分區到期時間。如要從現有資料表移除分區到期時間，您必須明確將選項設為所選值，或手動修改資料表。
資料表類型。執行成功後，資料表會回報為資料表副本 (INFORMATION_SCHEMA.TABLES 中的 table_type = 'CLONE')。其行為與標準資料表相同，且副本中繼資料中顯示的基礎資料表已不存在。
資料表層級中繼資料和資料列存取權政策。資料表層級標記和資料列層級存取權政策不會在執行作業之間保留。資料表建立完成後，您可以在 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` 參照其他表格