建立資料表

在 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 Core 建立資料表。

關於資料表定義

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

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

除了在 type: "table" SLQX 檔案中定義資料表，您也可以在 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 檔案，請按照下列步驟操作：

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 Core 建立資料表分區和叢集。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 只會根據您設定的條件，將新資料列插入或合併至增量資料表。

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

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

效能最佳化

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

縮短延遲

您可以運用增量資料表快速但頻繁地執行工作流程，減少輸出資料表的下游延遲。

每日數據匯報

您可以設定增量資料表，每天建立資料表資料的快照，例如，長期分析儲存在正式版資料庫中的使用者設定。

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

如要決定 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. 使用參照已宣告變數的 WHERE 子句，篩選定義資料表的 SELECT 陳述式。
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 選項，或在觸發工作流程執行時選取「以完整重新整理方式執行」選項。

選取完整重新整理選項後，Dataform 會在開發工作區中或使用 Dataform CLI 時忽略 ${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

透過 include 重複使用資料欄說明文件

您可以使用 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 標籤新增至資料表定義檔案，請按照下列步驟操作：

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 建立工作流程」。
• 如要瞭解如何透過 include 重複使用程式碼，請參閱「 透過 include 在單一存放區中重複使用程式碼」。
• 如要瞭解如何使用 Dataform 指令列介面，請參閱「使用 Dataform CLI」。