Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

管理存放區

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

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

事前準備

選取或建立存放區。

注意： Dataform 存放區清單只會列出為 Dataform 工作流程開發作業建立的存放區。BigQuery Studio 資產 (例如筆記本或已儲存的查詢) 的存放區是分開管理，不會顯示在這個清單中。
選用：將存放區連結至第三方 Git 存放區。
在存放區中建立並初始化開發工作區。

必要的角色

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

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

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

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

調整 Dataform 工作流程設定

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

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

關於存放區設定

所有存放區都必須使用自訂服務帳戶執行工作流程，並強制執行嚴格的「以身分執行」模式。您無法使用預設 Dataform 服務代理執行工作流程。

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

自 Dataform Core 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`」

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
  dataformCoreVersion: 3.0.62
  preserveGovernanceControls: true

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

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

如未設定 defaultLocation 參數，Dataform 會根據 SQL 查詢參照的資料集決定位置。運作方式如下：
- 如果查詢參照相同位置的資料集，Dataform 會使用該位置。
- 如果查詢參照兩個或多個不同位置的資料集，就會發生錯誤。如要進一步瞭解這項限制，請參閱「跨區域資料集複製」。
- 如果查詢未參照任何資料集，Dataform 的預設位置為US多區域。如要選擇其他位置，請設定預設位置。或者，在查詢中使用@@location 系統變數。詳情請參閱「指定位置」。
defaultAssertionDataset：Dataform 會在其中建立檢視表的 BigQuery 資料集，檢視表會含有斷言結果，預設名稱為 dataform_assertions。
dataformCoreVersion：存放區中安裝的 Dataform 核心套件版本。詳情請參閱「管理 Dataform 核心套件」。
preserveGovernanceControls (選用)：布林值，指定在工作流程執行期間重建資料表時，Dataform 是否自動保留現有的 BigQuery 資料政策和資料治理標記 (搶先版)。詳情請參閱「保留存取權控管中繼資料」。

如要進一步瞭解 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 Google Cloud 專案 ID。
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 檔案中的 defaultDataset 和 defaultAssertionSchema 屬性，或 dataform.json 檔案中的 defaultSchema 和 assertionSchema 屬性。

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

`workflow_settings.yaml`

在開發工作區的「Files」窗格中，按一下 workflow_settings.yaml 檔案。
編輯 defaultDataset、defaultAssertionSchema 的值，或同時編輯兩者。

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

  ...
  defaultDataset: mytables
  ...

`dataform.json`

在開發工作區的「Files」窗格中，按一下 dataform.json 檔案。
編輯 defaultSchema、assertionSchema 或兩者的值。

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

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

建立自訂編譯變數

編譯變數包含的值，可透過版本設定或 Dataform API 要求中的編譯覆寫值進行修改。

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

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

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

`workflow_settings.yaml`

前往 Dataform 開發工作區。
在「Files」窗格中，選取 workflow_settings.yaml 檔案。
輸入下列程式碼片段：
```
"vars": {
  "VARIABLE":"VALUE"
}
```
更改下列內容：
- VARIABLE：變數名稱
- VALUE：編譯變數的預設值

下列程式碼範例顯示 workflow_settings.yaml 檔案中設為 myVariableValue 的 myVariableName 編譯變數：

...
vars:
  myVariableName: myVariableValue
...

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

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

`dataform.json`

前往 Dataform 開發工作區。
在「Files」窗格中，選取 dataform.json 檔案。
輸入下列程式碼片段：
```
"vars": {
  "VARIABLE":"VALUE"
}
```
更改下列內容：
- VARIABLE：變數名稱
- VALUE：編譯變數的預設值

下列程式碼範例顯示 dataform.json 檔案中設為 myVariableValue 的 myVariableName 編譯變數：

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

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

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database",
"defaultLocation": "us-west-1",
"vars": {
"executionSetting":"dev"
}
}

在資料表中新增編譯變數

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

前往 Dataform 開發工作區。
在「Files」(檔案) 窗格中，選取 SQLX 資料表定義檔案。
在檔案中，以以下格式輸入 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!"
  )}

設定 Iceberg 資料表的工作流程層級預設值

您可以在 workflow_settings.yaml 檔案中，為 Apache Iceberg 代管資料表提供工作流程層級的預設值。您可以為 bucket 名稱、資料表資料夾根目錄和資料表資料夾子路徑設定預設值。

如果您未在資料表定義檔案的 config 區塊中設定這些值，Dataform 會使用這些預設值，為 Iceberg 受管理資料表建構儲存空間 URI。

如要為表格設定工作流程層級的預設值，請將 defaultIcebergConfig 區塊和下列欄位新增至 workflow_settings.yaml 檔案：

bucketName：選用。Cloud Storage bucket 的預設名稱。
tableFolderRoot：選用。Cloud Storage bucket 內第一層資料夾的預設名稱。
tableFolderSubpath：選用。tableFolderRoot 內子資料夾的預設名稱。

下列程式碼範例顯示 workflow_settings.yaml 檔案，其中包含 Iceberg 代管資料表的工作流程層級預設值：

defaultProject: "defaultProject"
defaultDataset: "defaultDataset"
defaultLocation: "us-central1"
defaultIcebergConfig:
  bucketName: "wsDefaultBucketName"
  tableFolderRoot: "wsDefaultTableFolderRoot"
  tableFolderSubpath: "wsDefaultTableFolderSubpath"

您可以在 Dataform 程式碼中，以 ProjectConfig 物件屬性的形式存取這些欄位：

dataform.ProjectConfig.defaultIcebergConfig.bucketName
dataform.ProjectConfig.defaultIcebergConfig.tableFolderRoot
dataform.ProjectConfig.defaultIcebergConfig.tableFolderSubpath

詳情請參閱「建立 Apache Iceberg 代管資料表」和 iceberg 區塊屬性。

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

為確保工作流程設定檔與未來的 Dataform 核心框架版本相容，請將工作流程設定從 dataform.json 檔案遷移至 workflow_settings.yaml 檔案。

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

如果 Dataform 核心是存放區中唯一的依附元件套件，則 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，請按照下列步驟操作：

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

前往 Dataform
依序選取存放區和工作區。
在「Files」(檔案) 窗格中，依序點選「add 新增」和「Create file」(建立檔案)。
在「Add a file path」(新增檔案路徑) 欄位中，輸入 workflow_settings.yaml。
點選「建立檔案」。
在 workflow_settings.yaml 檔案中，新增 dataform.json 檔案的設定，並對應至 YAML 格式。
在「Files」(檔案) 窗格中，點按 dataform.json 旁的「更多」選單，然後點選「刪除」。
如要確認刪除 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。

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

將 Dataform Core 移至 `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 檔案，請按照下列步驟操作：

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

前往 Dataform
依序選取存放區和工作區。
在「Files」窗格中，選取 workflow_settings.yaml 檔案。
在 workflow_settings.yaml 檔案中，按照下列格式新增 Dataform 核心套件：
```
dataformCoreVersion: "VERSION"
```
將 VERSION 替換為最新版本的 Dataform，例如 3.0.0。
在「Files」(檔案) 窗格中，點選 package.json 檔案旁的「More」(更多) 選單，然後按一下「Delete」(刪除)。
如要確認刪除 dataform.json 檔案，請按一下「刪除」。
按一下「安裝套件」。

將 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 核心套件，請按照下列步驟操作：

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

前往 Dataform
選取存放區，然後選取工作區。
在「Files」(檔案) 窗格中，依序點選「add」「Add」(新增) 和「Create file」(建立檔案)。
在「Add a file path」(新增檔案路徑) 欄位中，輸入 package.json。
點選「建立檔案」。
在 package.json 檔案中，按照下列格式新增 Dataform 核心套件：
```
{
    "dependencies": {
        "@dataform/core": "VERSION"
    }
}
```
將 VERSION 替換為最新版本的 Dataform，例如 3.0.0。
按一下「Install packages」。
在「檔案」窗格中，選取 workflow_settings.yaml。
在 workflow_settings.yaml 檔案中，刪除 dataformCoreVersion 屬性。

更新 Dataform Core

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

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

在 GitHub 的 Dataform 版本頁面中，查詢 @dataform/core 的最新版本。
前往 Google Cloud 控制台的「Dataform」頁面。

前往 Dataform
依序選取存放區和工作區。
在「檔案」窗格中，選取 package.json 檔案或 workflow_settings.yaml 檔案。

Dataform 核心依附元件套件的設定位置，取決於 Dataform 核心版本和套件使用方式。詳情請參閱「管理 Dataform 核心套件位置」。
將 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。
按一下「Install packages」。
提交變更。
將變更推送至存放區。

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

{
    "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」(提取) 選項。如要將存放區的變更內容拉取至開發工作區，請按照下列步驟操作：

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

修訂變更

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

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

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

在「Dataform」頁面選取存放區。
在存放區頁面選取開發工作區。
在開發工作區頁面，按一下「Commit」(修訂)。
在「New commit」(新增修訂版本) 窗格中，執行下列操作：
1. 在「新增修訂版本訊息」欄位中，輸入修訂版本的說明。
2. 選取要修訂的已變更檔案。
  
  如未選取任何檔案，Dataform 會修訂所有本機變更。您可以依檔案狀態、檔案名稱和路徑篩選變更的檔案。
3. 按一下「Commit All changes」或「Commit X changes」。
  
  按鈕名稱取決於您選取要修訂的檔案。

推送變更

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

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

還原未提交的變更

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

在「Dataform」頁面選取存放區。
在存放區頁面中，選取開發工作區。
在「Files」(檔案) 窗格上方，按一下「More」(更多) 選單，然後選取「Revert to last commit」(還原至上次修訂版本)。

解決合併衝突

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

當您從分支提取內容，而其他使用者已將衝突的變更推送至相同分支時，通常會發生合併衝突。您必須編輯受影響的檔案，手動解決合併衝突。

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

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

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

在開發工作區的「Files」(檔案) 窗格中，選取受影響的檔案。
編輯檔案並套用所選變更。
提交變更。
選用：推送變更。

找出 BigQuery 資產的存放區

由其他 BigQuery 功能 (例如筆記本或已儲存的查詢) 自動建立及管理的 Dataform 存放區，會隱藏在 Google Cloud 控制台的 Dataform 中，以減少雜亂，並防止意外修改功能專屬邏輯。這些存放區可能會顯示在 Cloud Asset Inventory 搜尋或 IAM 權限稽核中，但不會顯示在 Google Cloud 控制台的 Dataform 中。

您可以檢查資源標籤，找出 Dataform 存放區的來源。下表說明各種 BigQuery 功能使用的標籤：

功能	標籤鍵	標籤值
BigQuery 存放區	`origin`	`bigquery-studio`
BigQuery Studio Git 存放區	`origin`	`bigquery-studio-git-folder`
資料畫布	`single-file-asset-type`	`data_canvas`
資料準備	`single-file-asset-type`	`data_preparation`或`data_preparation_sqlx`
Notebooks	`single-file-asset-type`	`notebook`
Pipelines	`bigquery-workflow`	(任何值)
已儲存的查詢	`single-file-asset-type`	`sql`

如要從未顯示在 Dataform 中的存放區擷取標籤，請選取下列其中一個選項：

控制台

前往 Google Cloud 控制台的「Asset Inventory」(資產清查) 頁面。

前往 Asset Inventory
按一下「資源」分頁標籤。
在「篩選結果」窗格中，按一下「資源類型」旁的「查看更多」，然後輸入 dataform.googleapis.com/Repository。
選取「dataform.Repository」，然後按一下「套用」。
在結果表格中找出存放區，然後查看「標籤」欄。將找到的標籤與說明各種 BigQuery 功能所用標籤的表格進行比對，找出來源功能。

API

如要擷取標籤，請使用 projects.locations.repositories.get 方法。使用下列資訊執行 API 要求：

端點：GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID

或者，您也可以在終端機執行下列 curl 指令：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID"

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION：Dataform 資源所在的區域。
REPOSITORY_ID：您要查詢的 Dataform 存放區專屬 ID。

回應中傳回的 projects.locations.repositories 資源包含標籤對應，其中含有用於識別來源特徵的中繼資料。

gcloud

在 Google Cloud CLI 執行下列指令，擷取特定存放區的標籤：

gcloud asset search-all-resources \
    --asset-types=dataform.googleapis.com/Repository \
    --query="name:projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID" \
    --format="yaml(labels)"

更改下列內容：

PROJECT_ID：Google Cloud 專案的專屬 ID。
LOCATION：存放區所在的 Google Cloud 區域。
REPOSITORY_ID：新 Dataform 存放區的專屬 ID。

如要找出與輸出標籤對應的資源，請前往 Google Cloud 控制台中的相符功能頁面，例如 BigQuery Studio 左側窗格「Explorer」分頁中的「Notebooks」或「資料畫布」資料夾。

後續步驟

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

管理存放區 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

調整 Dataform 工作流程設定

關於存放區設定

關於「workflow_settings.yaml」

關於「dataform.json」

設定結構定義名稱

workflow_settings.yaml

dataform.json

建立自訂編譯變數

workflow_settings.yaml

dataform.json

在資料表中新增編譯變數

設定 Iceberg 資料表的工作流程層級預設值

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

管理 Dataform 核心套件

管理 Dataform 核心套件位置

將 Dataform Core 移至 workflow_settings.yaml

將 Dataform 核心移至 package.json

更新 Dataform Core

package.json

workflow_settings.yaml

對程式碼進行版本管控

提取變更

修訂變更

推送變更

還原未提交的變更

解決合併衝突

找出 BigQuery 資產的存放區

控制台

API

gcloud

後續步驟

管理存放區

關於「`workflow_settings.yaml`」

關於「`dataform.json`」

`workflow_settings.yaml`

`dataform.json`

`workflow_settings.yaml`

`dataform.json`

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

將 Dataform Core 移至 `workflow_settings.yaml`

將 Dataform 核心移至 `package.json`

`package.json`

`workflow_settings.yaml`