本文提供 Dataform 存放區的下列資訊:
Dataform 存放區最佳做法總覽
本節概略說明在 Dataform 中管理存放區大小、存放區結構和程式碼生命週期的最佳做法。
存放區大小的最佳做法
存放區大小會影響 Dataform 開發作業的多個層面,例如:
- 協同合作
- 程式碼集可讀性
- 開發流程
- 工作流程編譯
- 工作流程執行作業
Dataform 會強制執行編譯資源的 API 配額和限制。如果存放區過大,可能會超過這些配額和限制。這可能會導致工作流程編譯和執行失敗。
為降低這項風險,建議您拆分大型存放區。分割大型存放區時,您會將大型工作流程分割成多個較小的工作流程,這些工作流程位於不同的存放區,並透過跨存放區依附元件連結。
這個方法可讓您遵守 Dataform 配額和限制、實施精細的程序和權限,以及提升程式碼集的可讀性和協作效率。不過,管理分割存放區可能比管理單一存放區更具挑戰性。
如要進一步瞭解 Dataform 存放區大小的影響,請參閱「存放區大小總覽」。如要進一步瞭解分割存放區的最佳做法,請參閱「分割存放區」。
存放區結構的最佳做法
建議您在 definitions 目錄中建立檔案結構,反映工作流程的階段。請注意,您可以採用最符合需求的自訂結構。
以下建議的 definitions 子目錄結構反映了大多數工作流程的重要階段:
sources:用於儲存資料來源宣告。intermediate:用於儲存資料轉換邏輯。output:用於儲存輸出資料表的定義。extras(選用),用於儲存其他檔案。
Dataform 中所有檔案的名稱都必須符合 BigQuery 資料表命名規範。建議 Dataform 存放區 definitions 目錄中的檔案名稱,能反映子目錄結構。
如要進一步瞭解在存放區中建構及命名檔案的最佳做法,請參閱「在存放區中建構程式碼」。
程式碼生命週期的最佳做法
Dataform 的預設程式碼生命週期包含下列階段:
在 Dataform 工作區中開發工作流程程式碼。
您可以使用 Dataform Core 或僅使用 JavaScript 進行開發。
-
您可以使用版本設定和工作區編譯覆寫設定,自訂編譯結果。
您可以透過版本設定,為整個存放區設定自訂編譯結果。您之後可以在工作流程設定中排定執行時間。
您可以透過工作區編譯覆寫設定,為存放區中的所有工作區建立編譯覆寫設定,為每個工作區建立自訂編譯結果。
在 BigQuery 中執行編譯結果。
您可以透過工作流程設定,排定執行作業或存放區編譯結果。
如要在 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 編譯資源限制」。
預估存放區的編譯資源用量
您可以估算存放區下列編譯資源的用量:
如要大致估算存放區目前的編譯時間用量,可以在本機 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 目錄中建構工作流程程式碼,原因如下:
- 將團隊指派給工作流程的特定部分,改善程式碼集協作。
- 在組織異動時,提高工作流程的可維護性。
- 改善程式碼集的導覽功能。
- 提升程式碼集的可擴充性。
- 盡可能減少團隊的管理負擔。
建議的 definitions 目錄結構
Dataform 存放區中的根目錄 definitions 包含建立工作流程元素的程式碼。您可以將 definitions 目錄中的檔案整理成反映工作流程結構的目錄結構。
開發工作流程時,您會宣告來源資料表並加以轉換,建立可用於業務或分析目的的輸出資料表。
工作流程可分為三個主要階段:
- 資料來源宣告。
- 轉換來源資料。
- 轉換後來源資料的輸出資料表定義。
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 資料表視為資料轉換邏輯,用於建立輸出資料表。
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
命名策略
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 計時器。如需詳細的重試程式碼範例和疑難排解步驟,請參閱「無法連線至遠端存放區」。
後續步驟
- 如要進一步瞭解 Dataform 中的程式碼生命週期,以及不同的設定方式,請參閱「Dataform 中的程式碼生命週期簡介」。
- 如要進一步瞭解工作流程生命週期的最佳做法,請參閱「工作流程生命週期的最佳做法」。
- 如要進一步瞭解編譯資源限制,請參閱「Dataform 編譯資源限制」。
- 如要瞭解如何將 Dataform 存放區連結至第三方 Git 存放區,請參閱「連結至第三方 Git 存放區」。
- 如要進一步瞭解 Dataform 中的工作流程,請參閱「工作流程總覽」。