存放區最佳做法

本文提供 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 會對編譯資源強制執行用量限制。

存放區可能因下列原因超出用量限制:

  • 存放區程式碼中的無限迴圈錯誤。
  • 存放區程式碼中的記憶體流失錯誤。
  • 存放區規模龐大,約有超過 1, 000 項工作流程動作。

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

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

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

  • CPU 作業時間用量。
  • Wall time 用量。
  • 在存放區中定義的動作,其生成圖表的序列化資料大小總計上限。

如要大致估算存放區目前的編譯時間用量,可以在本機 Linux 或 macOS 機器上,測量 Dataform 工作流程的編譯時間。

  • 如要設定工作流程的編譯時間,請在存放區中執行下列格式的 Dataform CLI 指令 dataform compile:

    time dataform compile
    

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

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

您可以將 real 結果視為 wall time 用量的粗略指標,並將 user 結果視為存放區編譯作業 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 執行資料表後,由程序或工具 (例如 BI) 使用的資料表定義。
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 將intermediate資料表執行至 BigQuery 後,就不會再用於其他用途 (例如資料分析)。您可以將 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

編譯和排程的最佳做法

為存放區設定排定的執行作業和自動化調度管理工作流程時,請遵循下列最佳做法,確保編譯作業穩定可靠:

  • 使用版本設定排定正式版執行作業:版本設定會按照可預測的時間表編譯存放區程式碼,並儲存編譯結果。執行正式環境執行管道時,系統會立即根據這個儲存的結果執行,不會向遠端 Git 存放區發出網路要求。
  • 限制 commitish 編譯,僅用於開發和低頻率工作:直接在 Git commitish (例如分支、標記或修訂版本 SHA) 上呼叫 CreateCompilationResult 時,Dataform 必須在每次叫用時透過網路複製存放區。請避免設定正式環境 Cron 工作或自動化調度管理 DAG,以高頻率重複從 Git commitish 編譯。
  • 設定自動重試和錯開排程:如果架構需要從外部排程器中的 Git commitish 進行編譯,請設定自動重試和指數輪詢,並錯開並行 cron 計時器。如需詳細的重試程式碼範例和疑難排解步驟,請參閱「無法連線至遠端存放區」。

後續步驟