管理存放區

本文說明如何在 Dataform 中執行下列操作:

事前準備

  1. 建立存放區
  2. 選用:將存放區連結至第三方 Git 存放區
  3. 在存放區中建立並初始化開發工作區

必要的角色

如要取得完成本文工作所需的權限,請要求管理員授予下列 IAM 角色:

  • 設定 Dataform 設定,並管理 Dataform 核心套件的位置: 存放區的「Dataform 管理員」 (roles/dataform.admin) 。
  • 更新 Dataform 核心套件,並在 Dataform 中使用版本管控: Dataform 編輯器 (roles/dataform.editor) 工作區。

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

設定 Dataform 工作流程

本節說明如何編輯特定存放區的 Dataform 工作流程處理設定。

您可能想編輯設定檔,重新命名結構定義或在存放區中新增自訂編譯變數

關於存放區設定

每個 Dataform 存放區都包含專屬的工作流程設定檔。這個檔案包含 Google Cloud 專案 ID 和結構定義,Dataform 會在 BigQuery 中發布資產。Dataform 會使用預設設定,但您可以編輯設定檔來覆寫預設設定,以符合自身需求。

Dataform Core 3.0.0 起,工作流程設定預設會儲存在 workflow_settings.yaml 檔案中。在舊版 Dataform Core 中,工作流程設定會儲存在 dataform.json 檔案中。Dataform Core 3.0 workflow_settings.yaml 檔案可回溯相容於 dataform.json 檔案。您仍可繼續使用 dataform.json 檔案儲存工作流程設定。最佳做法是將存放區工作流程設定遷移workflow_settings.yaml 格式,確保日後相容性。

關於「workflow_settings.yaml

workflow_settings.yaml 檔案是在 Dataform Core 3.0 中導入,會以 YAML 格式儲存 Dataform 工作流程設定。

以下程式碼範例舉例說明 workflow_settings.yaml 檔案:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

在上述程式碼範例中,鍵/值組合的說明如下:

  • defaultProject:您的 BigQuery 專案 ID。 Google Cloud
  • defaultDataset:Dataform 會在其中建立資產的 BigQuery 資料集,預設稱為 dataform
  • defaultLocation (選用):預設的 BigQuery 資料集位置。Dataform 會使用這個位置處理程式碼並儲存結果。這個處理位置必須與 BigQuery 資料集的位置相同。不過,這項設定不需要與 Dataform 存放區位置相符。

    如果未設定 defaultLocation 參數,Dataform 會根據 SQL 查詢參照的資料集判斷位置。運作方式如下:

    • 如果查詢參照相同位置的資料集,Dataform 會使用該位置。
    • 如果查詢參照來自兩個以上不同位置的資料集,就會發生錯誤。如要進一步瞭解這項限制,請參閱「跨區域資料集複製」。
    • 如果查詢未參照任何資料集,Dataform 的預設位置為 US 多地區。如要選擇其他位置,請設定預設位置。或者,在查詢中使用@@location 系統變數。詳情請參閱「指定位置」。
  • defaultAssertionDataset:Dataform 會在其中建立檢視表的 BigQuery 資料集,檢視表會含有斷言結果,預設稱為 dataform_assertions

如要進一步瞭解 workflow_settings.yaml 屬性,請參閱 GitHub 中的「WorkflowSettings」。

您可以在 Dataform 程式碼中,以 dataform.projectConfig 物件的屬性形式,存取 workflow_settings.yaml 中定義的屬性。

下列是從 workflow_settings.yaml 選項到可透過程式碼存取的 dataform.projectConfig 選項的對應:

  • defaultProject => defaultDatabase
  • defaultDataset => defaultSchema
  • defaultAssertionDataset => assertionSchema
  • projectSuffix => databaseSuffix
  • datasetSuffix => schemaSuffix
  • namePrefix => tablePrefix

下列程式碼範例顯示檢視區塊 SELECT 陳述式中參照的 dataform.projectConfig 物件:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

關於「dataform.json

dataform.json 檔案會以 JSON 格式儲存 Dataform 工作流程設定。

以下程式碼範例舉例說明 dataform.json 檔案:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

在上述程式碼範例中,鍵/值組合的說明如下:

  • warehouse:指向 BigQuery 的指標,Dataform 會在其中建立資產。
  • defaultDatabase:您的 BigQuery 專案 ID。 Google Cloud
  • defaultSchema:Dataform 會在其中建立資產的 BigQuery 資料集。
  • defaultLocation (選用):預設的 BigQuery 資料集位置。Dataform 會使用這個位置處理程式碼並儲存結果。這個處理位置必須與 BigQuery 資料集的位置相同。不過,這項設定不需要與 Dataform 存放區位置相符。

    如果未設定 defaultLocation 參數,Dataform 會根據 SQL 查詢參照的資料集判斷位置。運作方式如下:

    • 如果查詢參照相同位置的資料集,Dataform 會使用該位置。
    • 如果查詢參照來自兩個以上不同位置的資料集,就會發生錯誤。如要進一步瞭解這項限制,請參閱「跨區域資料集複製」。
    • 如果查詢未參照任何資料集,Dataform 的預設位置為 US 多地區。如要選擇其他位置,請設定預設位置。或者,在查詢中使用@@location 系統變數。詳情請參閱「指定位置」。
  • assertionSchema:Dataform 會在其中建立檢視表的 BigQuery 資料集,檢視表會含有斷言結果,預設稱為 dataform_assertions

您可以在專案程式碼中,以 dataform.projectConfig 物件的屬性形式,存取 dataform.json 檔案中定義的屬性。

設定結構定義名稱

如要設定結構定義名稱,請編輯 workflow_settings.yaml 檔案中的 defaultDatasetdefaultAssertionSchema 屬性,或 dataform.json 檔案中的 defaultSchemaassertionSchema 屬性。

如要設定結構定義的名稱,請按照下列步驟操作:

workflow_settings.yaml

  1. 在開發工作區的「Files」窗格中,按一下 workflow_settings.yaml 檔案。

  2. 編輯 defaultDatasetdefaultAssertionSchema 的值,或同時編輯兩者。

下列程式碼範例顯示 workflow_settings.yaml 檔案中定義的自訂 defaultDataset 名稱:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. 在開發工作區的「Files」窗格中,按一下 dataform.json 檔案。

  2. 編輯 defaultSchemaassertionSchema 的值,或同時編輯兩者。

下列程式碼範例顯示 dataform.json 檔案中定義的自訂 defaultSchema 名稱:

{
  ...
  "defaultSchema": "mytables",
  ...
}

建立自訂編譯變數

編譯變數包含的值可透過發布設定或 Dataform API 要求中的編譯覆寫項目修改。

workflow_settings.yaml 中定義彙整變數並新增至所選表格後,您可以在發布設定或 Dataform API 編譯覆寫中修改其值,有條件地執行表格。

如要進一步瞭解如何使用編譯變數有條件地執行資料表,請參閱「Dataform 中的程式碼生命週期簡介」。

如要建立可在整個存放區使用的編譯變數,請按照下列步驟操作:

workflow_settings.yaml

  1. 前往 Dataform 開發工作區。
  2. 在「Files」窗格中,選取 workflow_settings.yaml 檔案。
  3. 輸入下列程式碼片段:

    "vars": {
      "VARIABLE":"VALUE"
    }
    

    更改下列內容:

    • VARIABLE:變數名稱
    • VALUE:編譯變數的預設值

以下程式碼範例顯示 workflow_settings.yaml 檔案中設為 myVariableValuemyVariableName 編譯變數:

...
vars:
  myVariableName: myVariableValue
...

下列程式碼範例顯示 workflow_settings.yaml 檔案,其中 executionSetting 編譯變數設為 dev

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. 前往 Dataform 開發工作區。
  2. 在「Files」窗格中,選取 dataform.json 檔案。
  3. 輸入下列程式碼片段:

    "vars": {
      "VARIABLE":"VALUE"
    }
    

    更改下列內容:

    • VARIABLE:變數名稱
    • VALUE:編譯變數的預設值

以下程式碼範例顯示 dataform.json 檔案中設為 myVariableValuemyVariableName 編譯變數:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

下列程式碼範例顯示 dataform.json 檔案,其中 executionSetting 編譯變數設為 dev

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}
在表格中新增編譯變數

如要將編譯變數新增至 SQLX 資料表定義檔案,請按照下列步驟操作:

  1. 前往 Dataform 開發工作區。
  2. 在「檔案」窗格中,選取 SQLX 資料表定義檔案。
  3. 在檔案中,以以下格式輸入 when 子句:

    ${when(dataform.projectConfig.vars.VARIABLE === "SET_VALUE", "CONDITION")}
    

    更改下列內容:

    • VARIABLE:變數名稱,例如 executionSetting
    • SET_VALUE:變數的值,例如 staging
    • CONDITION:執行資料表的條件

下列程式碼範例顯示含有 when 子句的資料表定義 SQLX 檔案,以及在暫存執行設定中執行 10% 資料的 executionSetting 變數:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

以下程式碼範例顯示含有 when 子句和 myVariableName 變數的檢視區塊定義 SQLX 檔案:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

將工作流程設定遷移至 workflow_settings.yaml

為確保工作流程設定檔與日後的 Dataform Core 架構版本相容,您應將工作流程設定從 dataform.json 檔案遷移至 workflow_settings.yaml 檔案。

workflow_settings.yaml 檔案會取代 dataform.json 檔案。

如果存放區中只有 Dataform Core 依附元件套件,workflow_settings.yaml 檔案也會取代 package.json 檔案。如要進一步瞭解如何以 workflow_settings.yaml 檔案取代 package.json 檔案,請參閱「管理 Dataform 核心套件」。

下表顯示 dataform.json 檔案中的工作流程設定屬性如何對應至 workflow_settings.yaml 檔案:

dataform.json的房地產 workflow_settings.yaml的房地產 說明
assertionSchema defaultAssertionDataset 這是必要旗標,斷言的預設資料集。
defaultDatabase defaultProject 這是必要旗標,預設 Google Cloud 專案名稱。
defaultLocation defaultLocation (選用步驟) Dataform 建立資料表的預設 BigQuery 位置。如未設定,Dataform 會根據 SQL 查詢參照的資料集判斷位置。詳情請參閱「指定位置」。
defaultSchema defaultDataset 這是必要旗標,預設資料集。
databaseSuffix projectSuffix (選用步驟) 要附加至所有 Google Cloud 專案參照的後置字元。
schemaSuffix datasetSuffix (選用步驟) 要附加至所有動作資料集的後置字元。
tablePrefix namePrefix (選用步驟) 要加到所有動作名稱的前置字串。
vars vars (選用步驟) 編譯期間可供專案程式碼使用的使用者定義變數。這個物件中包含 key: value 組合的清單,
warehouse - dataform.json 中必須填寫。必須設為 bigquery。不適用於「workflow_settings.yaml」。
- dataformCoreVersion dataform.json」不支援這項功能。新存放區預設會安裝在 workflow_settings.yaml 中。詳情請參閱「管理 Dataform 核心套件」。

如要將工作流程設定遷移至 workflow_settings.yaml,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取存放區,然後選取工作區。

  3. 在「檔案」窗格中,依序點選「新增」和「建立檔案」

  4. 在「Add a file path」(新增檔案路徑) 欄位中,輸入 workflow_settings.yaml

  5. 點選「建立檔案」

  6. workflow_settings.yaml 檔案中,新增 dataform.json 檔案中的設定,並對應至 YAML 格式。

  7. 在「檔案」窗格中,點選 dataform.json 旁的「更多」選單,然後點選「刪除」

  8. 如要確認刪除 dataform.json,請按一下「刪除」

下列程式碼範例顯示在 dataform.json 檔案中定義的工作流程設定:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

下列程式碼範例顯示轉換為 workflow_settings.yaml 的前述 dataform.json 檔案:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

管理 Dataform 核心套件

本節說明如何管理 Dataform 核心架構依附元件套件,並更新至最新版本。

Dataform Core 是開放原始碼的 Dataform 架構,可使用 SQL、SQLX 和 JavaScript 開發工作流程。最佳做法是使用最新版本的 Dataform 核心架構。如要瞭解 Dataform 核心架構的版本資訊,請參閱 GitHub 上的 Dataform 版本

管理 Dataform 核心套件位置

在存放區中初始化第一個工作區時,Dataform 會自動將 Dataform Core 設為依附元件套件。自 Dataform Core 3.0.0 起,Dataform 預設會在 workflow_settings.yaml 檔案中安裝 Dataform Core 套件。在舊版 Dataform Core 中,Dataform Core 是在 package.json 檔案中設定。

在 Dataform Core 3.0.0 以上版本中,如果存放區中只有 Dataform Core 套件,則應在 workflow_settings.yaml 檔案中設定。如果是使用舊版 Dataform Core 建立的存放區,請將 Dataform Core 套件移至 workflow_settings.yaml

如要在 Dataform 中安裝其他套件,必須有 package.json 檔案。如果存放區使用其他套件,請在 package.json 中設定 Dataform 核心套件,以便集中設定所有套件。如果存放區沒有 package.json 檔案,請建立 package.json 檔案並移動 Dataform 核心套件,安裝其他套件。

將 Dataform 核心移至 workflow_settings.yaml

如果是使用 3.0.0 之前的 Dataform Core 版本建立存放區,且除了 Dataform Core 以外沒有其他依附元件套件,請將 Dataform Core 套件從 package.json 檔案移至 workflow_settings.yaml 檔案,並刪除多餘的 package.json 檔案。

如要將 Dataform 核心套件從 package.json 檔案遷移至 workflow_settings.yaml 檔案,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取存放區,然後選取工作區。

  3. 在「Files」窗格中,選取 workflow_settings.yaml 檔案。

  4. workflow_settings.yaml 檔案中,按照下列格式新增 Dataform 核心套件:

    dataformCoreVersion: "VERSION"
    
    

    VERSION 替換為最新版本的 Dataform,例如 3.0.0

  5. 在「檔案」窗格中,點選 package.json 檔案旁的「更多」選單,然後點選「刪除」

  6. 如要確認刪除 dataform.json 檔案,請按一下「刪除」

  7. 按一下「安裝套件」

將 Dataform 核心移至 package.json

如要在存放區中安裝其他套件,必須使用 package.json 檔案。如果存放區使用其他套件,您應將所有套件 (包括 Dataform 核心套件) 儲存在 package.json 檔案中。

如果存放區沒有 package.json 檔案 (因為 Dataform 核心套件是在 workflow_settings.yaml 檔案中設定),您必須建立 package.json 檔案來安裝其他套件,然後將 Dataform 核心套件從 workflow_settings.yaml 檔案移至新建立的 package.json 檔案。

如要建立 package.json 檔案並移動 Dataform 核心套件,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取存放區,然後選取工作區。

  3. 在「檔案」窗格中,依序點選「新增」和「建立檔案」

  4. 在「Add a file path」(新增檔案路徑) 欄位中,輸入 package.json

  5. 點選「建立檔案」

  6. package.json 檔案中,按照下列格式新增 Dataform 核心套件:

    {
        "dependencies": {
            "@dataform/core": "VERSION"
        }
    }
    

    VERSION 替換為最新版 Dataform,例如 3.0.0

  7. 按一下「安裝套件」

  8. 在「檔案」窗格中,選取 workflow_settings.yaml

  9. workflow_settings.yaml 檔案中,刪除 dataformCoreVersion 屬性。

更新 Dataform Core

在實際工作環境中部署前,請務必先在非實際工作環境中測試新版套件。

如要更新 Dataform 核心依附元件套件,請按照下列步驟操作:

  1. GitHub 的 Dataform 版本頁面上,查看最新版本的 @dataform/core

  2. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  3. 選取存放區,然後選取工作區。

  4. 在「檔案」窗格中,選取 package.json 檔案或 workflow_settings.yaml 檔案。

    Dataform Core 依附元件套件的設定位置,取決於 Dataform Core 版本和套件使用方式。詳情請參閱「管理 Dataform 核心套件位置」。

  5. 使用最新版本更新 Dataform 核心依附元件套件:

    package.json

    {
        "dependencies": {
            "@dataform/core": "VERSION"
        }
    }
    

    請將 VERSION 換成最新版本的 Dataform,例如 3.0.0。為避免套件安裝問題,請明確指定 Dataform 核心套件版本。請勿使用 package.json 檔案的其他 dependencies 選項,例如 >version

    workflow_settings.yaml

    dataformCoreVersion: "VERSION"
    

    VERSION 替換為最新版本的 Dataform,例如 3.0.0

  6. 按一下「安裝套件」

  7. 修訂變更

  8. 將變更推送至存放區

下列程式碼範例顯示 @dataform/core 依附元件已在 package.json 檔案中更新為 3.0.0 版本:

{
    "dependencies": {
        "@dataform/core": "3.0.0"
    }
}

管控程式碼版本

本節說明如何在 Dataform 中使用版本控管功能追蹤開發作業進度。

Dataform 會使用 Git 追蹤存放區內檔案的每次變更。

在 Dataform 存放區中,您可以直接與 Git 存放區互動。

在已連結的存放區中,您可以與連結存放區時設定的遠端存放區追蹤分支互動。

Dataform 會根據開發工作區的變更狀態,顯示版本管控選項。舉例來說,只有在工作區中有未提交的本機變更時,Dataform 才會顯示提交選項。如果工作區中的檔案與預設或追蹤分支完全相同,Dataform 會顯示「工作區為最新狀態」狀態。

Dataform 會顯示下列版本控管選項:

修訂 X 項變更
在工作區或所選已變更的檔案中,提交 X 個本機變更。Dataform 會顯示未提交的變更。
推送至預設分支版本
將已提交的變更推送至預設分支版本。如果工作區中沒有未提交的變更,即可在 Dataform 存放區中使用這個選項。
推送至「your-branch-name
將已提交的變更推送至 your-branch-name。如果存放區已連結至第三方 Git 存放區,且工作區中沒有未提交的變更,即可使用這個選項。
從預設分支版本提取
使用預設分支版本的最新變更更新工作區。如果工作區中沒有未提交或未推送的已提交變更,即可在 Dataform 存放區中使用這個選項。
從「your-branch-name」提取
your-branch-name 更新工作區,套用最近的變更。如果存放區已連線至第三方 Git 存放區,且工作區中沒有未提交或未推送的已提交變更,即可使用這項選項。
還原為上次修訂版本
將工作區中的檔案還原為上次提交時的狀態。

提取變更

如果開發工作區與存放區不同步,Dataform 會顯示「Pull」(提取) 選項。如要將存放區的變更內容拉取至開發工作區,請按照下列步驟操作:

  1. 在「Dataform」頁面中,選取存放區。
  2. 在「Development workspaces」(開發工作區) 分頁中,選取開發工作區。
  3. 在開發工作區頁面中執行下列操作:
    1. 如果您位於 Dataform 存放區,請按一下「從預設分支版本提取」
    2. 如果您位於已連結至第三方 Git 存放區的存放區中,請按一下「從 your-branch-name 提取」

修訂變更

在開發工作區中進行變更後,Dataform 會顯示「提交」選項。您可以提交所有本機變更或選取的檔案。

在「New commit」(新增提交) 對話方塊中,Dataform 會顯示未提交的變更。

如要將開發工作區的變更提交至存放區,請按照下列步驟操作:

  1. 在「Dataform」頁面中,選取存放區。
  2. 在存放區頁面中,選取開發工作區。
  3. 在開發工作區頁面中,按一下「Commit」(提交)
  4. 在「New commit」(新增提交) 窗格中,執行下列操作:

    1. 在「新增提交訊息」欄位中,輸入提交的說明。
    2. 選取要修訂的已變更檔案。

      如未選取任何檔案,Dataform 會修訂所有本機變更。您可以依檔案狀態、檔案名稱和路徑篩選變更的檔案。

    3. 按一下「Commit All changes」或「Commit X changes」

      按鈕名稱會因您選取的待提交檔案而異。

推送變更

提交變更後,Dataform 會顯示「推送」選項。 如要將開發工作區的變更推送到存放區,請按照下列步驟操作:

  1. 在「Dataform」頁面中,選取存放區。
  2. 在存放區頁面中,選取開發工作區。
  3. 修訂變更
  4. 在開發工作區頁面中執行下列操作:
    1. 如果您位於 Dataform 存放區,請按一下「Push to default branch」(推送至預設分支版本)
    2. 如果您位於已連結至第三方 Git 存放區的存放區中,請按一下「推送至 your-branch-name

還原未提交的變更

如要還原未提交的變更,請按照下列步驟操作:

  1. 在「Dataform」頁面中,選取存放區。
  2. 在存放區頁面中,選取開發工作區。
  3. 在「檔案」窗格上方,按一下「更多」選單,然後選取「還原至上次提交」

解決合併衝突

如果開發工作區中的本機變更與存放區預設追蹤分支版本中的變更不相容,就可能發生合併衝突。如果多位使用者同時編輯同一個檔案,通常會發生合併衝突。

通常在其他使用者將衝突變更推送至相同分支後,您從分支提取時會遇到合併衝突。您必須編輯受影響的檔案,手動解決合併衝突。

以下程式碼範例顯示 SQLX 檔案中顯示的合併衝突:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

如要解決合併衝突,請按照下列步驟操作:

  1. 在開發工作區的「Files」(檔案) 窗格中,選取受影響的檔案。
  2. 編輯檔案,進行所選變更。
  3. 修訂變更
  4. 選用:推送變更

後續步驟