Dataform 簡介

本文將介紹 Dataform 的概念和程序。

Dataform 這項服務可讓資料分析師在 BigQuery 中開發、測試、版本管控，並安排資料轉換複雜的工作流程。

Dataform 可讓您在資料整合的擷取、載入和轉換 (ELT) 程序中，管理資料轉換作業。從來源系統擷取原始資料並載入 BigQuery 後，Dataform 可協助您將資料轉換為定義完善、經過測試且附有說明文件的資料表套件。

您可以使用 Dataform 執行下列資料轉換動作：

• 開發及執行資料轉換工作流程。
• 透過 Git 與團隊成員協作開發工作流程。
• 管理大量資料表及其依附元件。
• 宣告來源資料並管理資料表依附元件。
• 查看工作流程的依附元件樹狀結構。
• 在中央存放區中，使用 SQL 程式碼管理資料。
• 使用 JavaScript 重複使用程式碼。
• 對來源和輸出資料表執行品質測試，確認資料是否正確。
• 控管 SQL 程式碼版本。
• 在 SQL 程式碼中記錄資料表。

Dataform 中的資料轉換程序

Dataform 的資料轉換工作流程如下：

1. 您可以使用 Dataform 建立存放區來管理程式碼。
2. 您可以使用 Dataform 建立開發用工作區。
3. 您可以在 Dataform 的開發工作區中開發工作流程。
4. Dataform 會將 Dataform Core 編譯為 SQL。
5. Dataform 會執行依附元件樹狀結構。

您可以使用 Dataform 建立存放區來管理程式碼

在 Dataform 存放區中，您可以使用 SQL 的擴充功能 Dataform Core，編寫 SQLX 檔案來定義工作流程。Dataform 存放區支援版本控管。您可以將 Dataform 存放區連結至第三方 Git 供應商。

您可以使用 Dataform 建立開發用工作區

您可以在 Dataform 存放區中建立開發工作區，進行 Dataform 核心開發。在開發工作區中，您可以變更存放區、編譯、測試，並透過 Git 將變更推送至主要存放區。

您可以在開發工作區中開發 Dataform 核心

在開發工作區中，您可以定義及記錄表格、表格的依附元件和轉換邏輯，以建構工作流程。您也可以在 JavaScript 中設定動作。

Dataform 會編譯 Dataform 核心

在編譯期間，Dataform 會執行下列工作：

• 將 Dataform 核心編譯為標準 SQL 工作流程。
• 在程式碼中加入樣板 SQL 陳述式，例如 CREATE TABLE 或 INSERT，並搭配查詢設定。
• 將 JavaScript 轉譯 (從來源到來源編譯) 為 SQL。
• 解決依附元件問題，並檢查錯誤，包括遺失或循環依附元件。
• 建構要在 BigQuery 中執行的所有動作的依附元件樹狀結構。

Dataform 編譯是密封的，可驗證編譯一致性，也就是說，每次編譯相同程式碼時，都會產生相同的 SQL 編譯結果。Dataform 會在無法存取網際網路的沙箱環境中編譯程式碼。編譯期間無法執行其他動作，例如呼叫外部 API。

如要即時偵錯，您可以在開發工作區的互動式圖表中，檢查專案的已編譯工作流程。

Dataform 會執行依附元件樹狀結構

在 BigQuery 中，Dataform 會執行下列工作：

• 按照依附元件樹狀結構的順序執行 SQL 指令。
• 對資料表和檢視區塊執行斷言查詢，檢查資料是否正確。
• 執行您定義的其他 SQL 作業。

執行完畢後，您就可以將資料表和檢視畫面用於所有分析用途。

您可以查看記錄，瞭解建立的資料表、判斷是否通過或未通過斷言、各項動作的完成時間，以及其他資訊。您也可以查看 BigQuery 中執行的確切 SQL 程式碼。

Dataform 功能

您可以使用 Dataform 開發資料表、遞增資料表或檢視區塊，並部署至 BigQuery。Dataform 提供網頁環境，可執行下列活動：

• 工作流程開發
• 與 GitHub、GitLab、Azure DevOps Services 和 Bitbucket 建立連線
• 持續整合和持續部署
• 工作流程執行作業

以下各節說明 Dataform 的主要功能。

存放區

每個 Dataform 專案都會儲存在存放區中。Dataform 存放區會儲存一系列 JSON 設定檔、SQLX 檔案和 JavaScript 檔案。

Dataform 存放區包含下列類型的檔案：

• 設定檔

  您可以使用設定 JSON 或 SQLX 檔案設定工作流程。 其中包含一般設定、執行時間表，或是用於建立新資料表和檢視區塊的結構定義。

• 定義

  定義是 SQLX 和 JavaScript 檔案，用於定義要在 BigQuery 中執行的新資料表、檢視區塊和其他 SQL 作業。

• 包含

  Includes 是 JavaScript 檔案，您可以在其中定義要在專案中使用的變數和函式。

每個 Dataform 存放區都會連結至服務帳戶。您可以在建立存放區時選取服務帳戶，也可以稍後編輯服務帳戶。

根據預設，Dataform 會使用從專案編號衍生出的服務帳戶，格式如下：

[e-mail]

版本管控

Dataform 會使用 Git 版本控制系統，記錄專案檔案的每次變更，並管理檔案版本。

每個 Dataform 存放區都可以管理自己的 Git 存放區，或連線至遠端第三方 Git 存放區。您可以將 Dataform 存放區連結至 GitHub、GitLab、Azure DevOps Services 或 Bitbucket 存放區。

使用者可以在 Dataform 工作區中控管工作流程程式碼的版本。在 Dataform 工作區中，您可以從存放區提取變更、提交所有或所選變更，並將變更推送至存放區的 Git 分支。

工作流程開發

在 Dataform 中，您可以在開發工作區內變更檔案和目錄。 開發工作區是 Git 存放區內容的可編輯虛擬副本。Dataform 會在工作階段之間保留開發工作區中的檔案狀態。

在開發工作區中，您可以使用 Dataform Core 搭配 SQLX 和 JavaScript，或僅使用 JavaScript，開發工作流程動作。您可以自動格式化 Dataform 核心或 JavaScript 程式碼。

Dataform 工作流程的每個元素 (例如資料表或斷言)，都對應到 Dataform 在 BigQuery 中執行的動作。舉例來說，資料表定義檔案是在 BigQuery 中建立或更新資料表的動作。

在 Dataform 工作區中，您可以開發下列工作流程動作：

• 來源資料聲明
• 資料表和檢視表
• 增量資料表
• 資料表分區和叢集
• 動作之間的相依性
• 資料表說明文件
• 自訂 SQL 作業
• BigQuery 標籤
• BigQuery 政策標記
• Dataform 標記
• 資料品質測試 (稱為斷言)

您可以使用 JavaScript，透過下列方式重複使用 Dataform 工作流程程式碼：

• 在具有程式碼封裝的檔案中
• 在包含項目的存放區中
• 在含有套件的存放區中

Dataform 會即時編譯工作區中的工作流程程式碼。在工作區中，您可以查看每個檔案中編譯的查詢和動作詳細資料。您也可以在編輯過的檔案或存放區中，查看編譯狀態和錯誤。

如要在將編譯後的 SQL 查詢傳送至 BigQuery 執行前測試輸出內容，可以在 Dataform 工作區中預覽查詢。

如要檢查工作區中定義的整個工作流程，可以查看互動式編譯圖表，當中會顯示工作流程中的所有編譯動作，以及這些動作之間的關係。

工作流程編譯

Dataform 會使用工作流程設定檔中設定的預設編譯設定，即時將工作區中的工作流程程式碼編譯為 SQL，並建立工作區的編譯結果。

您可以覆寫編譯設定，自訂 Dataform 將工作流程編譯為編譯結果的方式。

透過工作區編譯覆寫設定，您可以為存放區中的所有工作區設定編譯覆寫。您可以設定動態工作區覆寫，為每個工作區建立自訂編譯結果，將工作區變成獨立的開發環境。您可以覆寫 Dataform 執行工作區內容的 Google Cloud 專案、為所有已編譯資料表的名稱新增前置字串，以及為預設結構定義新增後置字串。

您可以透過版本設定，設定編譯設定範本，為 Dataform 存放區建立編譯結果。在發布設定中，您可以覆寫 Dataform 執行編譯結果的 Google Cloud 專案、為所有已編譯資料表的名稱新增前置字元、為預設結構定義新增後置字元，以及新增編譯變數。您也可以設定建立彙整結果的頻率。如要排定在所選版本設定中建立的編譯結果執行時間，可以建立工作流程設定。

工作流程執行作業

工作流程執行期間，Dataform 會執行工作流程的編譯結果，在 BigQuery 中建立或更新資產。

如要在 BigQuery 中建立或重新整理工作流程中定義的資料表和檢視區塊，您可以在開發工作區中手動啟動工作流程執行作業，或排定執行作業。

您可以在 BigQuery 中透過下列方式排定 Dataform 執行作業：

• 建立工作流程設定，排定在版本設定中建立的編譯結果執行時間
• 使用 Cloud Composer 排定執行時間
• 使用 Workflows 和 Cloud Scheduler 排定執行時間

如要偵錯錯誤，可以透過下列方式監控執行作業：

• 查看詳細的 Dataform 執行記錄
• 查看 Dataform 的稽核記錄
• 查看 Dataform 的 Cloud Logging 記錄

Dataform 核心

Dataform Core 是開放原始碼的元語言，可建立 SQL 資料表和工作流程。Dataform 核心提供依附關係管理系統、自動化資料品質測試和資料說明文件，擴充 SQL 的功能。

您可以使用 Dataform Core 執行下列作業：

• 定義資料表、檢視區塊、具體化檢視區塊或遞增資料表。
• 定義資料轉換邏輯。
• 宣告來源資料及管理資料表依附元件。
• 在程式碼中記錄資料表和資料欄說明。
• 在不同查詢中重複使用函式和變數。
• 編寫資料斷言，驗證資料一致性。

在 Dataform 中，您可以使用 Dataform Core 開發工作流程，並將資產部署至 BigQuery。

Dataform Core 是開放原始碼 Dataform 資料建模架構的一部分，也包含 Dataform CLI。您可以在 Google Cloud外部，透過 Dataform CLI 在本機編譯及執行 Dataform Core。

如要使用 Dataform Core，請編寫 SQLX 檔案。每個 SQLX 檔案都包含查詢，用於定義 Dataform 在 BigQuery 中建立及更新的資料庫關係。

Dataform 會即時編譯 Dataform 核心程式碼，建立可在 BigQuery 中執行的 SQL 編譯結果。

Dataform 編譯是密封的，可驗證編譯一致性，也就是說，每次編譯相同程式碼時，都會產生相同的 SQL 編譯結果。Dataform 會在無法存取網際網路的沙箱環境中編譯程式碼。編譯期間無法執行其他動作，例如呼叫外部 API。

SQLX 檔案設定區塊

SQLX 檔案包含設定區塊和主體。所有設定屬性和設定區塊本身都是選用項目。因此，任何純 SQL 檔案都是有效的 SQLX 檔案，Dataform 會照原樣執行。

在設定區塊中，您可以執行下列動作：

• 指定查詢中繼資料。
• 文件資料。
• 定義資料品質測試。

指定查詢中繼資料

您可以使用設定中繼資料，設定 Dataform 如何將查詢具體化為 BigQuery，例如輸出資料表類型、目標資料庫或標籤。

文件資料

您可以直接在設定區塊中記錄表格及其欄位。資料表的文件會直接推送至 BigQuery。您可以剖析這份文件，並將其推送至其他工具。

定義資料品質測試

您可以定義資料品質測試 (稱為「斷言」)，檢查唯一性、空值或自訂條件。建立資料表後，Dataform 會將設定區塊中定義的斷言新增至工作流程依附元件樹狀結構。您也可以在設定區塊以外定義斷言，也就是在個別的 SQLX 檔案中定義。

下列程式碼範例說明如何在 SQLX 檔案的設定區塊中，定義輸出資料表類型、記錄資料表，以及定義品質測試。

config {
  type: "table",
    description: "This table joins orders information from OnlineStore & payment information from PaymentApp",
  columns: {
    order_date: "The date when a customer placed their order",
    id: "Order ID as defined by OnlineStore",
    order_status: "The status of an order e.g. sent, delivered",
    customer_id: "Unique customer ID",
    payment_status: "The status of a payment e.g. pending, paid",
    payment_method: "How the customer chose to pay",
    item_count: "The number of items the customer ordered",
    amount: "The amount the customer paid"
  },
    assertions: {
    uniqueKey: ["id"]
  }
}

SQLX 檔案主體

在 SQLX 檔案主體中，您可以執行下列動作：

• 定義資料表及其依附元件。
• 定義要在 BigQuery 中執行的其他 SQL 作業。
• 使用 JavaScript 生成 SQL 程式碼。

定義資料表

如要定義新資料表，可以使用 SQL SELECT 陳述式和 ref 函式。

ref 函式是 SQLX 內建函式，在 Dataform 的依附元件管理中至關重要。ref 函式可讓您參照 Dataform 專案中定義的資料表，而不必對資料表的結構定義和資料表名稱進行硬式編碼。

Dataform 會使用 ref 函式，建構所有要建立或更新的資料表依附元件樹狀結構。編譯後，Dataform 會新增 CREATE、REPLACE 或 INSERT 等樣板陳述式。

下列程式碼範例說明如何使用 ref 函式，在 SQLX 檔案中參照資料表。

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, 3

輸出結果會與下列內容相似：

CREATE OR REPLACE TABLE Dataform.orders AS

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 Dataform_stg.store_clean

GROUP BY 1, 2, 3

如要進一步瞭解其他依附元件管理功能 (例如有條件地執行程式碼、使用其他 Dataform Core 內建函式)，請參閱 Dataform Core 參考資料。

定義其他 SQL 作業

如要設定 Dataform 在建立資料表或檢視區塊前後執行一或多個 SQL 陳述式，可以指定前置查詢和後置查詢作業。

下列程式碼範例說明如何在查詢後作業中，設定資料表或檢視畫面的存取權。

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer` ON TABLE ${self()} TO "group:[e-mail]"
}

封裝 SQL 程式碼

如要定義可重複使用的函式，產生重複的 SQL 程式碼部分，可以使用 JavaScript 區塊。您只能在定義 JavaScript 區塊的 SLQX 檔案中，重複使用該區塊定義的程式碼。如要在整個存放區中重複使用程式碼，可以建立包含項目。

如要動態修改查詢，您可以在主體中的任何位置使用內嵌 JavaScript。

下列程式碼範例說明如何在 SQLX 檔案中定義 JavaScript 區塊，並在查詢中內嵌使用：

js {
  const columnName = "foo";
}

SELECT 1 AS ${columnName} FROM "..."

限制

Dataform 目前有下列已知限制：

• Dataform in Google Cloud 會在純 V8 執行階段執行，且不支援 Node.js 提供的額外功能和模組。如果現有程式碼集需要任何 Node.js 模組，請移除這些依附元件。

  如果專案在 package.json 中沒有名稱欄位，每次安裝套件時，系統都會產生差異。package-lock.json如要避免這種情況，請在 package.json 中新增 name 屬性。

• 系統不支援 package.json 中依附元件的 git+https:// 網址。

  將這類網址轉換為純 https:// 封存網址。舉例來說，將 git+https://github.com/dataform-co/dataform-segment.git#1.5 轉換為 https://github.com/dataform-co/dataform-segment/archive/1.5.tar.gz。

• 無法手動執行單元測試。

• 無法在開發工作區中搜尋檔案內容。

  注意： 如要查看允許透過第三方遠端存放區使用 Dataform IP 位址時，可使用的輸出 IP 位址範圍清單，請參閱「Dataform 位置」一文。

• 自 Dataform Core 3.0.0.起，Dataform 不會發布 Docker 映像檔。您可以建構自己的 Dataform Docker 映像檔，用來執行等同於 Dataform CLI 指令的操作。如要建構自己的 Docker 映像檔，請參閱 Docker 說明文件中的「將應用程式容器化」。

• 下列 Dataform API 方法不符合 AIP.134 指南，會將 * 萬用字元項目視為錯誤要求，並在省略 field_mask 時更新所有欄位，而非設定欄位：

  • releaseConfigs - patch
  • repositories - patch
  • updateConfig
  • workflowConfigs - patch

後續步驟

• 如要進一步瞭解 Dataform 中的程式碼生命週期，請參閱「Dataform 中的程式碼生命週期簡介」。
• 如要進一步瞭解 Dataform 存放區，請參閱「存放區簡介」。
• 如要進一步瞭解 Dataform 工作區，請參閱「建立 Dataform 開發工作區」。
• 如要進一步瞭解如何在 Dataform 中開發工作流程，請參閱工作流程總覽。
• 如要進一步瞭解 Dataform CLI，請參閱「使用 Dataform CLI」。