管理存放區

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

• 設定 Dataform 工作流程設定。
• 管理 Dataform 核心套件。
• 管控程式碼版本。

事前準備

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

必要的角色

如要取得完成本文件中任務所需的權限，請管理員授予您下列 IAM 角色：

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

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

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

調整 Dataform 工作流程設定

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

您可能需要編輯設定檔，將結構定義重新命名，或將自訂編譯變數新增至存放區。

關於存放區設定

每個 Dataform 存放區都包含專屬的工作流程設定檔案。這個檔案包含 Google Cloud 專案 ID，以及 Dataform 在 BigQuery 中發布資產的結構定義。Dataform 會使用預設設定，您可以透過編輯設定檔覆寫這些設定，以便根據需求進行調整。

自 Dataform 核心 3.0.0起，工作流程設定預設會儲存在 workflow_settings.yaml 檔案中。在舊版 Dataform 核心中，工作流程設定會儲存在 dataform.json 檔案中。Dataform core 3.0 workflow_settings.yaml 檔案可向下相容 dataform.json 檔案。您可以繼續使用 dataform.json 檔案儲存工作流程設定。最佳做法是將存放區工作流程設定遷移至 workflow_settings.yaml 格式，以便日後相容。

關於「workflow_settings.yaml」

Dataform 核心 3.0 推出的 workflow_settings.yaml 檔案會以 YAML 格式儲存 Dataform 工作流程設定。

以下程式碼範例顯示 workflow_settings.yaml 檔案範例：

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

在上述程式碼範例中，鍵/值組合如下所示：

• defaultProject：您的 BigQuery Google Cloud 專案 ID。
• defaultDataset：Dataform 會在其中建立資產的 BigQuery 資料集，預設名稱為 dataform。
• defaultLocation：預設的 BigQuery 資料集區域。在這個位置，Dataform 會處理您的程式碼，並儲存執行的資料。這個處理區域必須與 BigQuery 資料集的位置相符，但不必與 Dataform 存放區區域相符。如要進一步瞭解 BigQuery 資料集位置，請參閱「資料集位置」。
• defaultAssertionDataset：Dataform 會在其中建立檢視表的 BigQuery 資料集，預設名稱為 dataform_assertions。

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

您可以透過 dataform.projectConfig 物件的屬性，存取 Dataform 程式碼中 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 Google Cloud 專案 ID。
• defaultSchema：Dataform 會在其中建立資產的 BigQuery 資料集。
• defaultLocation：預設的 BigQuery 資料集區域。在這個位置，Dataform 會處理您的程式碼，並儲存執行的資料。這個處理區域必須與 BigQuery 資料集的位置相符，但不必與 Dataform 存放區相符。如要進一步瞭解 BigQuery 資料集位置，請參閱「資料集位置」。
• assertionSchema：Dataform 會在其中建立檢視表的 BigQuery 資料集，預設名稱為 dataform_assertions。

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

設定結構定義名稱

如要設定結構定義名稱，您必須編輯 workflow_settings.yaml 檔案中的 defaultDataset 和 defaultAssertionSchema 屬性，或是 dataform.json 檔案中的 defaultSchema 和 assertionSchema 屬性。

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

  ...
  defaultDataset: mytables
  ...

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

建立自訂編譯變數

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

在 workflow_settings.yaml 中定義編譯變數並將其新增至所選表格後，您可以在發布設定中修改其值，或使用Dataform API 編譯覆寫值，以條件方式執行表格。

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

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

...
vars:
  myVariableName: myVariableValue
...

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

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

{
"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：執行資料表的條件

下列程式碼範例顯示資料表定義 SQLX 檔案，其中包含 when 子句和 executionSetting 變數，可在階段執行設定中執行 10% 的資料：

  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 核心架構版本相容，您應將工作流程設定從 dataform.json 檔案遷移至 workflow_settings.yaml 檔案。

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

如果資料表單核心是存放區中唯一的依附元件套件，workflow_settings.yaml 檔案也會取代 package.json 檔案。如要進一步瞭解如何用 workflow_settings.yaml 檔案取代 package.json 檔案，請參閱「管理 Dataform 核心套件」。

下表顯示工作流程設定屬性從 dataform.json 檔案對應至 workflow_settings.yaml 檔案的對應方式：

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

1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

   前往 Dataform

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

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

4. 在「新增檔案路徑」欄位中輸入 workflow_settings.yaml。

5. 點選「建立檔案」。

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

7. 在「檔案」窗格中，按一下 dataform.json 旁的「更多」選單，然後點選「刪除」。

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

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

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

以下程式碼範例顯示將前述 dataform.json 檔案轉換為 workflow_settings.yaml：

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

管理 Dataform 核心套件

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

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

管理 Dataform 核心套件位置

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

在 Dataform core 3.0.0 以上版本中，如果 Dataform core 是存放區中唯一的套件，則應在 workflow_settings.yaml 檔案中設定該套件。如果是使用舊版 Dataform 核心建立的存放區，請將 Dataform 核心套件移至 workflow_settings.yaml。

您必須使用 package.json 檔案，才能在 Dataform 中安裝其他套件。如果存放區使用其他套件，請在 package.json 中設定 Dataform 核心套件，以便將所有套件設在同一個位置。如果您的存放區沒有 package.json 檔案，請建立 package.json 檔案並移動 Dataform 核心套件，以便安裝其他套件。

將 Dataform 核心移至 workflow_settings.yaml

如果存放區是使用 3.0.0 之前的 Dataform 核心版本建立，且您沒有 Dataform 核心以外的依附元件套件，則應將 Dataform 核心套件從 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 檔案中。

如果 Dataform 核心套件已在 workflow_settings.yaml 檔案中設定，則存放區中不會包含 package.json 檔案，您必須建立 package.json 檔案才能安裝其他套件，然後將 Dataform 核心套件從 workflow_settings.yaml 檔案移至新建立的 package.json 檔案。

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

1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

   前往 Dataform

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

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

4. 在「新增檔案路徑」欄位中輸入 package.json。

5. 點選「建立檔案」。

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

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

   將 VERSION 替換為最新版的 Dataform，例如 3.0.0。

7. 按一下「安裝套件」。

8. 在「Files」窗格中，選取 workflow_settings.yaml。

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

更新資料表單核心

請務必先在非正式環境中測試新套件版本，再將其部署至正式環境。

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

1. 請前往 GitHub 上的 Dataform 版本頁面，查看 @dataform/core 的最新版本。

2. 在 Google Cloud 控制台中，前往「Dataform」頁面。

   前往 Dataform

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

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

   設定 Dataform 核心依附元件套件的地點，取決於您使用的 Dataform 核心版本和套件用途。詳情請參閱「管理 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 會顯示「Commit」選項。您可以提交所有本機變更或所選檔案。

在「New commit」對話方塊中，Dataform 會顯示未提交的變更。

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

1. 在「Dataform」頁面中，選取存放區。
2. 在存放區頁面中選取開發工作區。
3. 在開發工作區頁面中，按一下「提交」。

4. 在「New commit」窗格中，執行下列操作：

   1. 在「新增提交訊息」欄位中，輸入提交內容的說明。

   2. 選取要修訂的已變更檔案。

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

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

      按鈕名稱會因您要提交的檔案而異。

推送變更

提交變更後，Dataform 會顯示「Push」選項。如要將變更從開發工作區推送至存放區，請按照下列步驟操作：

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. 選用：推送變更。

後續步驟

• 如要進一步瞭解 Dataform 專案設定，請參閱 IProjectConfig 參考資料。
• 如要瞭解如何安裝其他套件，請參閱「在 Dataform 中安裝套件」。
• 如要瞭解如何建立資料表，請參閱「建立資料表」。