存放區的最佳做法

本文將介紹 Dataform 存放區的下列資訊：

Dataform 存放區最佳做法總覽

本節概述在 Dataform 中管理存放區大小、存放區結構和程式碼生命週期的最佳做法。

存放區大小最佳做法

存放區大小會影響 Dataform 的多個開發層面，例如：

  • 協同合作
  • 程式碼集可讀性
  • 開發程序
  • 工作流程編譯
  • 工作流程執行作業

Dataform 會對編譯資源強制執行 API 配額和限制。如果存放區過大，可能會導致存放區超出這些配額和限制。這可能會導致工作流程編譯和執行失敗。

為降低這項風險，建議您分割大型存放區。 分割大型存放區時，您會將大型工作流程劃分為多個較小的工作流程，這些工作流程位於不同的存放區中，並透過跨存放區依附元件連結。

這個方法可讓您遵守 Dataform 配額和限制、實作精細的程序和權限，並提升程式碼庫的可讀性和協作性。不過，管理分割存放區可能比管理單一存放區更具挑戰性。

如要進一步瞭解存放區大小對 Dataform 的影響，請參閱「存放區大小總覽」。如要進一步瞭解如何分割存放區的最佳做法，請參閱「分割存放區」。

存放區結構的最佳做法

建議您在 definitions 目錄中建構檔案，以反映工作流程的各個階段。請注意，您可以採用最符合需求的自訂結構。

以下建議的子目錄結構反映了大多數工作流程的主要階段：definitions

  • sources，用於儲存資料來源宣告。
  • intermediate，用於儲存資料轉換邏輯。
  • output，用於儲存輸出資料表的定義。
  • extras (選用) 儲存其他檔案。

Dataform 中所有檔案的名稱都必須符合 BigQuery 資料表命名規範。建議您讓 Dataform 存放區中 definitions 目錄的檔案名稱反映子目錄結構。

如要進一步瞭解在存放區中建構及命名檔案的最佳做法，請參閱「在存放區中建構程式碼」。

程式碼生命週期的最佳做法

Dataform 的預設程式碼生命週期包含下列階段：

如要在 Dataform 中管理程式碼生命週期，您可以建立執行環境，例如開發、測試和正式環境。

如要進一步瞭解 Dataform 中的程式碼生命週期，請參閱「Dataform 中的程式碼生命週期簡介」。

您可以選擇將執行環境保留在單一或多個存放區中。

單一存放區中的執行環境

您可以在單一 Dataform 存放區中，使用工作區編譯覆寫和發布版本設定，建立獨立的執行環境，例如開發、測試和實際工作環境。

您可以透過下列方式建立獨立的執行環境：

  • 依結構定義分割開發和正式環境資料表。
  • 依結構定義和 Google Cloud 專案分割開發和實際工作環境資料表。
  • 依 Google Cloud 專案分割開發、測試和實際工作環境資料表。

然後，您可以使用工作流程設定，在測試和正式環境中排定執行作業。 建議您在開發環境中手動觸發執行作業。

如要進一步瞭解在 Dataform 中管理工作流程生命週期的最佳做法，請參閱「工作流程生命週期的最佳做法」。

多個存放區中的程式碼生命週期

如要根據程式碼生命週期的各個階段，調整身分與存取權管理權限，您可以建立多個存放區副本，並將這些副本儲存在不同的 Google Cloud 專案中。

每個 Google Cloud 專案都是執行環境，對應程式碼生命週期的階段，例如開發和正式環境。

採用這種做法時，建議您在所有專案中，讓存放區的程式碼集保持一致。如要自訂每個存放區副本的編譯和執行作業，請使用工作區編譯覆寫、版本設定和工作流程設定。

存放區大小總覽

本節將說明存放區大小對工作流程開發和 Dataform 編譯資源用量的影響，以及如何估算存放區的編譯資源用量。

關於 Dataform 存放區大小

存放區大小會影響 Dataform 開發作業的下列層面：

  • 協作工具：多位協作者處理大型存放區時，可能會建立過多的提取要求，增加合併衝突的風險。

  • 程式碼集可讀性。如果單一存放區中的工作流程包含大量檔案，可能會導致存放區難以瀏覽。

  • 開發程序。單一存放區中大型工作流程的某些區域可能需要自訂權限或程序 (例如排程)，這與套用至工作流程其餘部分的權限和程序不同。存放區過大會導致開發程序難以配合工作流程的特定領域。

  • 工作流程編譯。Dataform 會對編譯資源強制執行用量限制。如果存放區過大，可能會超過這些限制，導致編譯失敗。

  • 工作流程執行作業。執行期間，Dataform 會在工作區內執行存放區程式碼，並將資產部署至 BigQuery。存放區越大，Dataform 執行存放區所需的時間就越長。

如果存放區過大，對 Dataform 的開發作業造成負面影響，您可以將存放區分割成多個較小的存放區。

關於存放區編譯資源限制

在開發期間，Dataform 會編譯工作區中的所有存放區程式碼，以產生存放區中工作流程的表示法。這就是所謂的「編譯結果」。Dataform 會對編譯資源強制執行用量限制。

您的存放區可能因為下列原因超出用量限制：

  • 存放區程式碼中的無限迴圈錯誤。
  • 存放區程式碼中的記憶體流失錯誤。
  • 存放區大小較大，約有超過 1000 個工作流程動作。

如要進一步瞭解編譯資源的使用限制，請參閱「Dataform 編譯資源限制」。

預估存放區的編譯資源用量

您可以估算存放區的下列編譯資源用量：

  • CPU 時間用量。
  • 在存放區中定義的動作圖表，其序列化資料總大小上限。

如要概略估算存放區編譯作業目前的 CPU 時間用量，您可以在本機 Linux 或 macOS 電腦上計時編譯 Dataform 工作流程。

  • 如要計算工作流程的編譯時間，請在存放區中執行 Dataform CLI 指令 dataform compile，格式如下：

    time dataform compile

    下列程式碼範例顯示執行 time dataform compile 指令的結果：

    real    0m3.480s
user    0m1.828s
sys     0m0.260s

您可以將 real 結果視為存放區編譯的 CPU 時間用量指標。

如要概略估算存放區中產生的動作圖表總大小，您可以將圖表的輸出內容寫入 JSON 檔案。您可以將未壓縮的 JSON 檔案大小視為圖表總大小的粗略指標。

  • 如要將工作流程編譯圖的輸出內容寫入 JSON 檔案，請在存放區中執行下列 Dataform CLI 指令：

    dataform compile --json > graph.json

分割存放區

本節將探討分割 Dataform 存放區的策略，以及如何管理跨存放區的依附元件。

存放區是 Dataform 的核心單元。存放區會儲存構成工作流程的所有 SQLX 和 JavaScript 檔案，以及 Dataform 設定檔和套件。您可以將工作流程儲存在單一存放區，也可以將工作流程拆分到多個存放區。

在 Dataform 中分割存放區有以下優點：

  • 遵守編譯資源用量的 Dataform 限制。將大型工作流程拆分成多個較小的存放區，可降低編譯資源超出 Dataform 限制的風險。
  • 精細化流程。您可以為工作流程的每個分割片段和開發團隊個別設定程序，例如持續整合 (CI) 規則。
  • 精細控管權限。您可以為工作流程的每個分割片段和開發團隊個別設定權限，提升工作流程的整體安全性。
  • 減少處理工作流程各個分割片段的協作者人數，提升協作效率。
  • 提升程式碼集的可讀性。將大型工作流程的檔案分割成多個存放區，可讓您更輕鬆地個別瀏覽每個存放區，而不必一次瀏覽整個工作流程。
  • 與執行整個工作流程相比，加快工作流程每個分割片段的執行速度。

在 Dataform 中分割存放區有下列缺點：

  • 每個 Dataform 存放區及其對應的 Git 存放區都需要自訂持續整合和持續開發 (CI/CD) 設定。
  • 每個 Dataform 存放區及其對應的 Git 存放區都必須有自訂排程設定。
  • 難以管理工作流程物件之間的依附元件，這些物件存放在多個存放區中。
  • 無法全面呈現 SQL 工作流程的有向非循環圖 (DAG)，因為工作流程分散在多個存放區。在每個存放區中，產生的 DAG 只代表完整工作流程的一部分。

分割存放區的策略

分割存放區時，您會將構成父項 SQL 工作流程的檔案，劃分成較小的子項工作流程，並存放在不同的 Dataform 存放區中。

您可以選擇透過下列其中一種方式分割存放區：

  • 每個開發團隊只能有一個存放區。
  • 每個網域一個存放區，例如銷售、行銷或物流。
  • 一個中央存放區，以及每個網域各有一個存放區，這些存放區會使用中央存放區的內容做為資料來源。

如要在第三方 Git 託管平台中存放上層工作流程，您需要將包含子項工作流程的每個個別存放區，連線至專用的第三方 Git 存放區。

管理跨存放區依附元件

如要有效分割存放區，最簡單的方法是將父項 SQL 工作流程劃分為獨立的子項工作流程，然後建立獨立的存放區。獨立存放區不會使用其他存放區的內容做為資料來源。這種做法不需要管理跨存放區的依附元件。

如果無法避免跨存放區依附元件，您可以將存放區分割成一系列存放區，藉此管理依附元件。在這一系列存放區中，每個存放區都依附於前一個存放區，並做為後一個存放區的資料來源。存放區及其依附元件的順序必須最能反映父項工作流程的結構。

您可以使用 Dataform 資料來源宣告，在存放區之間建立依附元件。您可以在編輯中的存放區，將其他 Dataform 存放區的 BigQuery 資料表類型宣告為資料來源。宣告資料來源後，您就可以像其他 Dataform 工作流程動作一樣參照該來源，並用來開發工作流程。

如果工作流程分割在多個存放區，且存放區之間有相依性，您必須依存放區之間的相依性順序，逐一執行存放區。

建議您避免將存放區分割為一組具有雙向依附元件的存放區。當存放區是另一個存放區的資料來源，同時也將該存放區做為資料來源時，就會發生存放區之間的雙向依附元件。存放區之間的雙向依附元件會使父項工作流程的排程和執行作業，以及開發程序變得複雜。

在存放區中建構程式碼

本節說明在 Dataform 存放區的根 definitions 目錄中，建構及命名工作流程檔案的最佳做法。definitions 目錄的建議結構會反映工作流程的階段。您可以採用任何符合業務需求的結構。

您可能會基於下列原因，想在 definitions 目錄中建構工作流程程式碼：

  • 指派團隊負責工作流程的特定部分，提升程式碼的協作效率。
  • 在機構變更時，提高工作流程的維護性。
  • 改善程式碼庫的導覽體驗。
  • 提升程式碼集的擴充性。
  • 盡量減少團隊的行政負擔。

Dataform 存放區中的根 definitions 目錄包含用於建立工作流程元素的程式碼。您可以將 definitions 目錄中的檔案整理成目錄結構，反映工作流程的結構。

開發工作流程時，您會宣告來源資料表並加以轉換，建立可用於業務或分析目的的輸出資料表。

工作流程可分為三個主要階段：

  1. 宣告資料來源。
  2. 轉換來源資料。
  3. 從轉換後的來源資料定義輸出資料表。

definitions 目錄中的子目錄結構反映了工作流程的主要階段：

sources
資料來源宣告和來源資料的基本轉換，例如篩選。
intermediate
資料表和動作，會先從 sources 讀取及轉換資料，再讓您使用轉換後的資料定義 outputs 資料表。Dataform 將資料表匯入 BigQuery 後，通常不會再透過其他程序或工具 (例如商業智慧 (BI) 工具) 處理這些資料表。
outputs
供程序或工具 (例如商業智慧) 使用的資料表定義，Dataform 會在 BigQuery 中執行這些定義。
extra
工作流程主要管道以外的檔案，例如包含為額外用途 (如機器學習) 準備的工作流程資料的檔案。自訂子目錄 (選填)。

sources最佳做法

sources 子目錄包含工作流程的第一階段：宣告及基本轉換來源資料。

在 sources 子目錄中，儲存資料來源宣告和資料表，以篩選、分類、轉換或重新命名資料欄。

避免儲存合併多個來源資料的資料表。

轉換儲存在 intermediate 子目錄中的資料表 sources 資料。

如果您從多個集區 (例如 Google Ads 或 Google Analytics) 宣告資料來源，請為每個集區專門建立子目錄。

以下範例顯示 sources 的子目錄結構，其中包含兩個來源集區：

definitions/
    sources/
        google_ads/
            google_ads_filtered.sqlx
            google_ads_criteria_metrics.sqlx
            google_ads_criteria_metrics_filtered.sqlx
            google_ads_labels.sqlx
            google_ads_labels_filtered.sqlx
        google_analytics/
            google_analytics_users.sqlx
            google_analytics_users_filtered.sqlx
            google_analytics_sessions.sqlx

如果您在同一個結構定義中宣告多個資料來源資料表，可以將這些宣告合併到單一 JavaScript 檔案。

如要進一步瞭解如何使用 JavaScript 建立資料來源宣告，請參閱「完全使用 JavaScript 建立工作流程」。

下列程式碼範例顯示單一結構定義中的多個資料來源，這些來源在單一 JavaScript 檔案中宣告：

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

如要保護工作流程，避免受到資料來源變更影響，您可以為每個資料來源宣告建立檢視區塊，例如 analytics_users_filtered.sqlx。檢視畫面可包含來源資料的基本篩選和格式設定。 將檢視畫面儲存在 sources 子目錄中。

接著，建立 intermediate 或 outputs 資料表時，請參照檢視表，而非原始來源資料表。這種方法可讓您測試來源資料表。如果來源表格有所變更，您可以修改其檢視畫面，例如新增篩選器或重新轉換資料。

intermediate最佳做法

intermediate 子目錄包含工作流程的第二階段：轉換及匯總一或多個來源的來源資料。

在 intermediate 子目錄中，儲存可大幅轉換一或多個來源資料的檔案 (位於 sources 子目錄中)，例如聯結資料的資料表。intermediate 子目錄中的資料表通常會查詢來源資料表或其他 intermediate 資料表中的資料。

使用 intermediate 資料表建立 outputs 資料表。一般來說，Dataform 將資料表匯入 BigQuery 後，就不會用於其他用途 (例如資料分析)。intermediate您可以將intermediate資料表視為資料轉換邏輯，可建立輸出資料表。

建議您記錄並測試所有 intermediate 表格。

outputs最佳做法

outputs 子目錄包含工作流程的最後階段：從轉換後的資料建立輸出表格，以供業務用途。

在 outputs 目錄中，儲存您打算在 Dataform 將資料表匯入 BigQuery 後，用於其他程序或工具的資料表，例如報表或資訊主頁。outputs 目錄中的資料表通常會查詢 intermediate 資料表中的資料。

依據相關的業務實體 (例如行銷、訂單或數據分析) 將資料表分組。outputs為每個商家實體專門建立子目錄。

如要在 BigQuery 中分別儲存輸出資料表，您可以為輸出資料表設定專屬結構定義。如需設定資料表結構定義的操作說明，請參閱「覆寫資料表設定」。

以下範例顯示 outputs 的子目錄結構，其中包含 sales 和 marketing 業務實體：

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

建議您記錄並測試所有 outputs 表格。

命名策略

Dataform 中所有檔案的名稱都必須符合 BigQuery 資料表命名規範。

建議您在 Dataform 存放區的 definitions 目錄中，為檔案命名時反映子目錄結構。

在 sources 子目錄中，檔案名稱應指向與檔案相關的來源。在檔案名稱中加入來源名稱做為前置字串，例如 analytics_filtered.sqlx

在 intermediate 子目錄中，檔案名稱應識別子目錄，方便協作者清楚區分 intermediate 檔案。選取專屬前置字串，並只套用至 intermediate 目錄中的檔案，例如 stg_ads_concept.sqlx。

在 outputs 子目錄中，檔案名稱應簡潔明瞭，例如 orders.sqlx。如果不同實體子目錄中有名稱相同的 outputs 資料表，請新增可識別實體的前置字串，例如 sales_revenue.sqlx 或 ads_revenue.sqlx。

以下範例顯示 definitions 目錄內的子目錄結構，以及符合建議命名策略的檔案名稱：

definitions/
    sources/
        google_analytics.sqlx
        google_analytics_filtered.sqlx
    intermediate/
        stg_analytics_concept.sqlx
    outputs/
        customers.sqlx
        sales/
            sales.sqlx
            sales_revenue.sqlx
        ads/
            campaigns.sqlx
            ads_revenue.sqlx

後續步驟