此页面由 Cloud Translation API 翻译。

管理代码库

本文档介绍了如何在 Dataform 中执行以下操作：

配置 Dataform 工作流设置。
管理 Dataform 核心软件包。
对代码进行版本控制。

准备工作

所需的角色

如需获得完成本文档中任务所需的权限，请让管理员为您授予以下 IAM 角色：

配置 Dataform 设置并管理 Dataform 核心软件包的位置：代码库中的 Dataform 管理 (roles/dataform.admin)。
更新 Dataform 核心软件包并在 Dataform 中使用版本控制：工作区的 Dataform Editor (roles/dataform.editor)。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

配置 Dataform 工作流设置

本部分介绍了如何修改特定代码库的数据表单工作流处理设置。

您可能需要修改设置文件以重命名架构，或向代码库添加自定义编译变量。

代码库设置简介

每个 Dataform 代码库都包含一个唯一的工作流设置文件。该文件包含 Google Cloud 项目 ID 以及 Dataform 在 BigQuery 中发布资产时所用的架构。Dataform 使用默认设置，您可以通过修改设置文件来替换这些设置，以便尽可能满足您的需求。

从 Dataform 核心 3.0.0 开始，工作流设置默认存储在 workflow_settings.yaml 文件中。在较低版本的 Dataform 核心中，工作流设置存储在 dataform.json 文件中。Dataform 核心 3.0 workflow_settings.yaml 文件向后兼容 dataform.json 文件。您可以继续使用 dataform.json 文件存储工作流设置。最佳实践是将代码库工作流设置迁移到 workflow_settings.yaml 格式，以便日后兼容。

关于`workflow_settings.yaml`

workflow_settings.yaml 文件在 Dataform 核心 3.0 中引入，以 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：BigQuery 数据集，Dataform 在其中使用断言结果创建视图，默认称为 dataform_assertions。

如需详细了解 workflow_settings.yaml 属性，请参阅 GitHub 中的 WorkflowSettings。

您可以在 Dataform 代码中将 workflow_settings.yaml 中定义的属性作为 dataform.projectConfig 对象的属性进行访问。

以下是从 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：BigQuery 数据集，Dataform 在其中使用断言结果创建视图，默认称为 dataform_assertions。

您可以在项目代码中将 dataform.json 文件中定义的属性作为 dataform.projectConfig 对象的属性进行访问。

配置架构名称

如需配置架构名称，您需要修改 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 文件中将 myVariableName 编译变量设置为 myVariableValue 的操作：

...
vars:
  myVariableName: myVariableValue
...

以下代码示例展示了将 executionSetting 编译变量设置为 dev 的 workflow_settings.yaml 文件：

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 文件中将 myVariableName 编译变量设置为 myVariableValue 的操作：

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

以下代码示例展示了将 executionSetting 编译变量设置为 dev 的 dataform.json 文件：

{
"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!"
  )}

将工作流设置迁移到 `workflow_settings.yaml`

为确保您的工作流设置文件与未来的 Dataform 核心框架版本兼容，您应将工作流设置从 dataform.json 文件迁移到 workflow_settings.yaml 文件。

workflow_settings.yaml 文件将替换 dataform.json 文件。

如果 Dataform 核心是代码库中的唯一依赖项软件包，则 workflow_settings.yaml 文件也会替换 package.json 文件。如需详细了解如何将 package.json 文件替换为 workflow_settings.yaml 文件，请参阅管理 Dataform 核心软件包。

下表显示了工作流设置属性从 dataform.json 文件到 workflow_settings.yaml 文件的映射：

`dataform.json` 中的媒体资源	`workflow_settings.yaml` 中的媒体资源	说明
`assertionSchema`	`defaultAssertionDataset`	必需。断言的默认数据集。
`defaultDatabase`	`defaultProject`	必需。默认的 Google Cloud 项目名称。
`defaultLocation`	`defaultLocation`	必需。Dataform 将在其中创建表的默认 BigQuery 位置。如需详细了解 BigQuery 位置，请参阅数据集位置。
`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
选择一个代码库，然后选择一个工作区。
在文件窗格中，点击添加添加，然后点击创建文件。
在添加文件路径字段中，输入 workflow_settings.yaml。
点击创建文件。
在 workflow_settings.yaml 文件中，添加映射到 YAML 格式的 dataform.json 文件中的设置。
在文件窗格中，点击 dataform.json 旁边的更多菜单，然后点击删除。
如需确认删除 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 核心是用于使用 SQL、SQLX 和 JavaScript 开发工作流的开源 Dataform 框架。最佳实践是始终使用最新版本的 Dataform 核心框架。如需了解 Dataform 核心框架的版本，请参阅 GitHub 上的 Dataform 版本。

管理 Dataform 核心软件包位置

当您在代码库中初始化第一个工作区时，Dataform 会自动将 Dataform 核心设置为依赖项软件包。从 Dataform 核心 3.0.0 开始，Dataform 会默认在 workflow_settings.yaml 文件中安装 Dataform 核心软件包。在较低版本的 Dataform 核心中，Dataform 核心是在 package.json 文件中设置的。

在 Dataform 核心 3.0.0 及更高版本中，如果 Dataform 核心是代码库中的唯一软件包，则应在 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 文件，请执行以下操作：

在 Google Cloud 控制台中，进入 Dataform 页面。

前往 Dataform
选择一个代码库，然后选择一个工作区。
在 Files 窗格中，选择 workflow_settings.yaml 文件。
在 workflow_settings.yaml 文件中，使用以下格式添加 Dataform 核心软件包：
```
dataformCoreVersion: "VERSION"
```
将 VERSION 替换为最新版本的 Dataform，例如 3.0.0。
在文件窗格中，点击 package.json 文件旁边的更多菜单，然后点击删除。
如需确认删除 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
选择一个代码库，然后选择一个工作区。
在文件窗格中，点击添加添加，然后点击创建文件。
在添加文件路径字段中，输入 package.json。
点击创建文件。
在 package.json 文件中，使用以下格式添加 Dataform 核心软件包：
```
{
    "dependencies": {
        "@dataform/core": "VERSION"
    }
}
```
将 VERSION 替换为最新版本的 Dataform，例如 3.0.0。
点击安装软件包。
在 Files 窗格中，选择 workflow_settings.yaml。
在 workflow_settings.yaml 文件中，删除 dataformCoreVersion 属性。

更新了 Dataform 核心

请务必先在非生产环境中测试新软件包版本，然后再在生产环境中部署。

如需更新 Dataform 核心依赖项软件包，请按以下步骤操作：

在 GitHub 上的 Dataform 版本页面上查找最新版本的 @dataform/core。
在 Google Cloud 控制台中，进入 Dataform 页面。

前往 Dataform
选择一个代码库，然后选择一个工作区。
在 Files 窗格中，选择 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。
点击安装软件包。
提交更改。
将更改推送到代码库。

以下代码示例展示了 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 仓库中会提供此选项。
推送至“your-branch-name”: 将已提交的更改推送到 your-branch-name。如果您的工作区中没有未提交的更改，则已连接到第三方 Git 代码库的代码库中会提供此选项。
从默认分支拉取: 使用默认分支中的近期更改更新您的工作区。如果您的工作区中没有未提交或未推送的已提交更改，则 Dataform 代码库中会提供此选项。
从“your-branch-name”拉取: 根据 your-branch-name 中的最新更改更新您的工作区。如果您的工作区中没有未提交或未推送的已提交更改，与第三方 Git 代码库相关联的代码库中会提供此选项。
还原为上次提交的内容: 将工作区中的文件恢复为上次提交时的状态。

拉取更改

如果您的开发工作区与代码库不同步，Dataform 会显示拉取选项。如需将更改从代码库拉取到开发工作区，请按以下步骤操作：

在 Dataform 页面上，选择一个代码库。
在开发工作区标签页中，选择一个开发工作区。
在“开发工作区”页面上，执行以下操作：
1. 如果您位于 Dataform 仓库中，请点击从默认分支拉取。
2. 如果您当前所在的代码库已连接到第三方 Git 代码库，请点击从 your-branch-name 拉取。

提交更改

在开发工作区中进行更改后，Dataform 会显示提交选项。您可以提交所有本地更改或所选文件。

在新提交对话框中，Dataform 会显示未提交的更改。

如需将开发工作区中的更改提交到代码库，请按以下步骤操作：

在 Dataform 页面上，选择一个代码库。
在代码库页面上，选择一个开发工作区。
在开发工作区页面上，点击提交。
在新提交窗格中，执行以下操作：
1. 在添加提交消息字段中，为提交输入说明。
2. 选择您要提交的已更改文件。
  
  如果您未选择任何文件，Dataform 会提交所有本地更改。您可以按文件状态、文件名和路径过滤已更改的文件。
3. 点击提交所有更改或提交 X 更改。
  
  按钮名称取决于您选择要提交的文件。

推送更改

提交更改后，Dataform 会显示 Push 选项。如需将更改从开发工作区推送到代码库，请按以下步骤操作：

在 Dataform 页面上，选择一个代码库。
在代码库页面上，选择一个开发工作区。
提交更改。
在“开发工作区”页面上，执行以下操作：
1. 如果您位于 Dataform 仓库中，请点击推送到默认分支。
2. 如果您当前所在的代码库已关联到第三方 Git 代码库，请点击推送到 your-branch-name。

还原未提交的更改

如需还原未提交的更改，请按以下步骤操作：

在 Dataform 页面上，选择一个代码库。
在代码库页面上，选择一个开发工作区。
在 Files 窗格上方，点击 More 菜单，然后选择 Revert to last commit。

解决合并冲突

如果开发工作区中的本地更改与对代码库的默认跟踪分支所做的更改不兼容，就可能会发生合并冲突。当多个用户同时编辑同一文件时，通常会发生合并冲突。

通常，当其他用户将有冲突的更改推送到同一分支后，您从该分支拉取时就会遇到合并冲突。您需要手动解决合并冲突，方法是修改受影响的文件。

以下代码示例展示了 SQLX 文件中显示的合并冲突：

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

如需解决合并冲突，请按以下步骤操作：

在开发工作区中的 Files（文件）窗格中，选择受影响的文件。
使用您选择的更改修改文件。
提交更改。
可选：推送更改。

后续步骤

如需详细了解 Dataform 项目设置，请参阅 IProjectConfig 参考文档。
如需了解如何安装其他软件包，请参阅在 Dataform 中安装软件包。
如需了解如何创建表，请参阅创建表。

管理代码库

准备工作

所需的角色

配置 Dataform 工作流设置

代码库设置简介

关于workflow_settings.yaml

关于dataform.json

配置架构名称

workflow_settings.yaml

dataform.json

创建自定义编译变量

workflow_settings.yaml

dataform.json

向表格添加编译变量

将工作流设置迁移到 workflow_settings.yaml

管理 Dataform 核心软件包

管理 Dataform 核心软件包位置

将 Dataform 核心移至 workflow_settings.yaml

将 Dataform 核心移至 package.json

更新了 Dataform 核心

package.json

workflow_settings.yaml

对代码进行版本控制

拉取更改

提交更改

推送更改

还原未提交的更改

解决合并冲突

后续步骤

关于`workflow_settings.yaml`

关于`dataform.json`

`workflow_settings.yaml`

`dataform.json`

`workflow_settings.yaml`

`dataform.json`

将工作流设置迁移到 `workflow_settings.yaml`

将 Dataform 核心移至 `workflow_settings.yaml`

将 Dataform 核心移至 `package.json`

`package.json`

`workflow_settings.yaml`