建立資料表

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

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

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

您也可以定義資料表分區和叢集。

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

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

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

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

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

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

除了在 type: "table" SQLX 檔案中定義資料表外，您也可以在 type: "operations" SQLX 檔案中定義自訂 SQL 查詢，建立空資料表。您可能會想建立空白資料表，讓其他服務為其填入資料。

事前準備

1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

   前往 Dataform

2. 在存放區中建立並初始化開發工作區。

3. 選用：宣告資料來源。

必要的角色

如要取得完成本文件任務所需的權限，請要求管理員授予您工作區的 Dataform 編輯者 (roles/dataform.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

建立資料表

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

關於資料表定義

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

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

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

使用 ref 參照依附元件

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

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 檔案，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

   前往 Dataform

2. 如要開啟存放區，請按一下存放區名稱。

3. 如要開啟開發工作區，請按一下工作區名稱。

4. 在「檔案」窗格中，點選 definitions/ 旁的「更多」。

5. 點選「建立檔案」。

6. 在「Add a file path」欄位中，輸入檔案名稱，並在 definitions/ 後方加上 .sqlx。例如：definitions/my-table.sqlx。

   檔案名稱只能包含數字、英文字母、連字號和底線。

7. 點選「建立檔案」。

定義資料表類型

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

1. 在開發工作區的「檔案」窗格中，展開 definitions/ 目錄。
2. 選取要編輯的資料表定義 SQLX 檔案。

3. 在檔案中輸入下列程式碼片段：

   config { type: "TABLE_TYPE" }
   

   請將 TABLE_TYPE 替換為下列其中一種資料表類型：

   • table
   • incremental
   • view

4. 選用：如要定義具象化檢視畫面，請按照下列格式，在 type: "view" 下方輸入 materialized 屬性：

   config {
     type: "view",
     materialized: true
   }
   

   詳情請參閱 ITableConfig。

5. 選用步驟：按一下「格式」。

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

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

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

下列程式碼範例顯示含有 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 陳述式中未參照，但需要在目前資料表前執行的資料表依附元件，請按照下列步驟操作：

1. 在開發工作區的「檔案」窗格中，展開 definitions/ 目錄。
2. 選取要編輯的資料表定義 SQLX 檔案。

3. 在表格的 config 區塊中，輸入下列程式碼片段：

   dependencies: [ "DEPENDENCY_TABLE", ]
   

   將 DEPENDENCY_TABLE 替換為您要新增為依附元件的資料表檔案名稱。您可以輸入多個檔案名稱。

4. 選用步驟：按一下「格式」。

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

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

覆寫資料表設定

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

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

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

1. 前往開發工作區。

2. 在「檔案」窗格中展開 definitions/。

3. 開啟 SQLX 資料表定義檔案。

4. 在 config 區塊中輸入下列程式碼片段：

    {
      schema: "OVERRIDDEN_SCHEMA",
      database: "OVERRIDDEN_DATABASE",
      name: "OVERRIDDEN_NAME"
    }
   

   更改下列內容：

   • OVERRIDDEN_SCHEMA：您要建立資料表的 BigQuery 資料集。

   • OVERRIDDEN_DATABASE：您要建立資料表的 BigQuery 專案 ID。

   • OVERRIDDEN_NAME：資料表名稱，與 SQLX 資料表定義檔案名稱不同。

5. 選用步驟：按一下「格式」。

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

建立資料表分區和叢集

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

建立資料表分區

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

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 開啟資料表定義 SQLX 檔案。

4. 在 config 區塊中，按照下列格式在資料表類型宣告下方新增 bigquery 區塊：

   config {
     type: "table",
     bigquery: {
     }
   }
   

5. 在 bigquery 區塊中輸入下列程式碼片段：

       partitionBy: "PARTITION_EXPRESSION"
   

   將 PARTITION_EXPRESSION 替換為用於分割資料表的運算式。

6. 選用步驟：按一下「格式」。

下列程式碼範例說明如何在資料表定義 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))"
  }
}

設定分區篩選器

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

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 開啟分區資料表定義 SQLX 檔案。

4. 在 bigquery 區塊中輸入下列程式碼片段：

   requirePartitionFilter : true
   

5. 選用步驟：按一下「格式」。

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

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

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

設定分區的保留期限

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

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 開啟分區資料表定義 SQLX 檔案。

4. 在 bigquery 區塊中輸入下列程式碼片段：

   partitionExpirationDays: NUMBER_OF_DAYS
   

   將 NUMBER_OF_DAYS 替換為要保留分割區的天數。

5. 選用步驟：按一下「格式」。

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

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

建立資料表叢集

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

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 開啟資料表定義 SQLX 檔案。

4. 在 bigquery 區塊中輸入下列程式碼片段：

       clusterBy: ["CLUSTER_COLUMN"]
   

   將 CLUSTER_COLUMN 替換為您要用來將資料表分群的資料欄名稱。詳情請參閱 clustering_column_list。

5. 選用步驟：按一下「格式」。

以下程式碼範例顯示依據 name 和 revenue 資料欄叢集的分區資料表：

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

設定累加資料表

本節說明如何使用 Dataform core 設定遞增式資料表。

關於累加資料表

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

定義累加型資料表時，Dataform 只會在第一次建立累加型資料表。在後續執行作業期間，Dataform 只會根據您設定的條件，在增量資料表中插入或合併新資料列。

Dataform 只會將新資料列插入增補資料表中已存在的資料欄。如果您變更增量資料表定義查詢 (例如新增資料欄)，就必須從頭開始重建資料表。如要這麼做，請在下次觸發資料表執行作業時，選取「Run with full refresh」選項。

以下是一些常見的增量資料表用途：

效能最佳化

對於某些類型的資料 (例如網頁記錄或分析資料)，您可能只想處理新的記錄，而非重新處理整個資料表。

減少延遲時間

您可以使用增量表格快速執行工作流程，並且頻繁執行，藉此減少輸出表格的下游延遲時間。

每日數據匯報

您可以設定增量資料表，為資料表資料建立每日快照，例如，針對儲存在實際工作環境資料庫中的使用者設定進行長期分析。

處理增量資料表中的部分資料列

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

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

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 開啟增量資料表定義 SQLX 檔案。

4. 請按照下列格式輸入 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 處理的資料列，並進行完整重新整理。

5. 選用步驟：按一下「格式」。

以下程式碼範例顯示增量資料表，可逐步處理 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 值的資料列，而不是附加資料列。

如要設定增量資料表中的合併作業，請按照下列步驟操作：

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 選取增量資料表定義 SQLX 檔案

4. 在 config 區塊中，將所選資料欄設為 uniqueKey，格式如下：

   uniqueKey: ["COLUMN_NAME"]
   

   將 COLUMN_NAME 替換為所選欄的名稱。

5. 選用步驟：按一下「格式」。

以下程式碼範例顯示增量資料表，其中 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 設為只考量記錄的子集。

以下程式碼範例顯示增量分區資料表，其中合併作業是透過設定 uniqueKey 和 updatePartitionFilter 屬性而設定：

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 會根據參照的分區資料表的最新分區更新增量資料表，而不需要掃描整個資料表。

如要設定參照分區資料表的增量資料表，並避免完整掃描資料表，請按照下列步驟操作：

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

下列程式碼範例顯示增量資料表，其中參照的 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，請按照下列步驟操作：

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

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

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

新增表格說明

本節將說明如何在 Dataform 核心 SQLX 檔案中，新增資料表及其欄和記錄的說明。

您可以在 Dataform 的所有表格類型中新增表格、欄和記錄說明：表格、增量表格和檢視畫面。

建議您記錄下列資訊：

• 資料表的用途。
• 資料表中欄或記錄的內容或角色。
• 表格與工作流程的其他動作之間的關係，例如依賴目前表格的表格或檢視畫面。
• 套用至表格的斷言。
• 套用至表格的前置或後置運算。
• 表格的擁有者，也就是建立表格的使用者。如果有多名團隊成員共同處理工作流程，這項資訊可能會派上用場。

新增表格說明

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

1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

   前往 Dataform

2. 選取存放區。

3. 選取開發工作區。

4. 在「檔案」窗格中，按一下要編輯的資料表定義 SQLX 檔案。

5. 在檔案的 config 區塊中，使用下列格式輸入表格說明：

   description: "Description of the table",
   

6. 選用步驟：按一下「格式」。

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

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

新增資料欄和記錄說明

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

1. 在資料表定義檔案的 config 區塊中輸入 columns: {}。

2. 在 columns: {} 中，按照下列格式輸入資料欄說明：

   column_name: "Description of the column",
   

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

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

4. 選用步驟：按一下「格式」。

以下程式碼範例顯示 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

使用「收錄」重複使用資料欄說明

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

• 如要建立可重複使用的資料欄說明，請使用資料欄名稱和說明來定義 JavaScript 包含常數。

您可以定義常數，其中包含單一資料欄的說明，或是常數，其中包含集合或資料欄說明，以便重複使用資料表中所有資料欄的說明。如要進一步瞭解如何在 Dataform 中建立及使用包含項目，請參閱「透過包含項目在單一存放區重複使用程式碼」。

以下程式碼範例會顯示多個常數，並說明在 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 標籤，請按照下列步驟操作：

1. 前往開發工作區。
2. 在「檔案」窗格中展開 definitions/。
3. 選取 SQLX 資料表定義檔案。

4. 在 config 區塊中，以以下格式新增標籤：

   bigquery: {
       labels: {
         LABEL1: "VALUE_OF_LABEL1"
       }
     }
   

   更改下列內容：

   • LABEL1：標籤名稱
   • VALUE_OF_LABEL1：標籤的值

5. 選用：如要新增名稱含有特殊字元的標籤，請在引號 ("") 中輸入標籤名稱。

6. 選用步驟：按一下「格式」。

以下程式碼範例顯示在分割資料表定義 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

後續步驟

• 如要瞭解如何透過斷言測試資料表資料，請參閱「透過斷言測試資料表」。
• 如要瞭解如何使用 JavaScript 定義資料表，請參閱「使用 JavaScript 建立 Dataform 工作流程」。
• 如要瞭解如何透過包含項目重複使用程式碼，請參閱「透過包含項目在單一存放區重複使用程式碼」。
• 如要瞭解如何使用 Dataform 指令列介面，請參閱「使用 Dataform CLI」一文。