管理代码库

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

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

准备工作

1. 创建代码库。
2. 可选：将代码库连接到第三方 Git 代码库。
3. 在代码库中创建并初始化开发工作区。

所需的角色

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

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

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

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

配置 Dataform 工作流设置

本部分介绍了如何为特定代码库修改 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 代码库位置一致。

  如果您未设置 defaultLocation 参数，Dataform 会根据 SQL 查询引用的数据集确定位置。 其工作原理如下：

  • 如果您的查询引用了同一位置的数据集，Dataform 会使用该位置。
  • 如果您的查询引用了来自两个或更多不同位置的数据集，则会发生错误。如需详细了解此限制，请参阅跨区域数据集复制。
  • 如果查询未引用任何数据集，Dataform 的默认位置为 US 多区域。如需选择其他位置，请设置默认位置。或者，在查询中使用 @@location 系统变量。如需了解详情，请参阅指定位置。

• 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 代码库位置一致。

  如果您未设置 defaultLocation 参数，Dataform 会根据 SQL 查询引用的数据集确定位置。 其工作原理如下：

  • 如果您的查询引用了同一位置的数据集，Dataform 会使用该位置。
  • 如果您的查询引用了来自两个或更多不同位置的数据集，则会发生错误。如需详细了解此限制，请参阅跨区域数据集复制。
  • 如果查询未引用任何数据集，Dataform 的默认位置为 US 多区域。如需选择其他位置，请设置默认位置。或者，在查询中使用 @@location 系统变量。如需了解详情，请参阅指定位置。

• assertionSchema：BigQuery 数据集，Dataform 在其中使用断言结果创建视图，默认情况下称为 dataform_assertions。

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

配置架构名称

如需配置架构名称，您需要修改 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：表格的执行条件

以下代码示例展示了一个包含 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 核心框架版本兼容，您应将工作流设置从 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 文件的映射：

如需将工作流设置迁移到 workflow_settings.yaml，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往 Dataform 页面。

   前往 Dataform

2. 选择代码库，然后选择工作区。

3. 在文件窗格中，依次点击添加图标 添加和创建文件。

4. 在添加文件路径字段中，输入 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"
  }
}

以下代码示例展示了上述 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 核心版 3.0.0 及更高版本中，如果 Dataform 核心版是代码库中唯一的软件包，则应在 workflow_settings.yaml 文件中进行设置。对于使用早期版本的 Dataform 核心创建的代码库，请将 Dataform 核心软件包移至 workflow_settings.yaml。

如需在 Dataform 中安装其他软件包，必须使用 package.json 文件。如果您的代码库使用其他软件包，请在 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. 在文件窗格中，选择 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. 在添加文件路径字段中，输入 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 核心

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

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

1. 在 GitHub 上的 Dataform 版本页面上查找 @dataform/core 的最新版本。

2. 在 Google Cloud 控制台中，前往 Dataform 页面。

   前往 Dataform

3. 选择代码库，然后选择工作区。

4. 在文件窗格中，选择 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. 将更改推送到代码库。

以下代码示例展示了 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 会显示拉取选项。如需将代码库中的更改拉取到开发工作区，请按以下步骤操作：

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

提交更改

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

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

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

1. 在 Dataform 页面上，选择一个代码库。
2. 在代码库页面上，选择一个开发工作区。
3. 在开发工作区页面上，点击提交。

4. 在新提交窗格中，执行以下操作：

   1. 在添加提交消息字段中，输入提交说明。

   2. 选择您要提交的已更改文件。

      如果您未选择任何文件，Dataform 会提交所有本地更改。您可以按文件状态、文件名和路径过滤已更改的文件。

   3. 点击提交所有更改，或点击提交 X 项更改。

      按钮名称取决于您选择要提交的文件。

推送更改

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

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

还原未提交的更改

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

1. 在 Dataform 页面上，选择一个代码库。
2. 在代码库页面上，选择一个开发工作区。
3. 在文件窗格上方，点击更多菜单，然后选择恢复到上次提交。

解决合并冲突

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

通常，当您从某个分支拉取内容后，另一位用户已将冲突的更改推送到同一分支时，您会遇到合并冲突。 您需要通过修改受影响的文件来手动解决合并冲突。

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

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

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

1. 在开发工作区的文件窗格中，选择受影响的文件。
2. 根据您选择的更改修改文件。
3. 提交更改。
4. 可选：推送更改。

后续步骤

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