配置 Dataform 工作流设置

本页介绍了如何修改特定代码库的 Dataform SQL 工作流处理设置。

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

代码库设置简介

每个 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 数据集区域。 如需详细了解 BigQuery 数据集位置，请参阅数据集位置。在此位置，Dataform 会处理您的代码并存储已执行的数据。此处理区域必须与您的 BigQuery 数据集所在的位置一致，但不必与 Dataform 代码库区域一致。
• defaultAssertionDataset：BigQuery 数据集，Dataform 在其中使用断言结果创建视图，默认称为 dataform_assertions。

如需详细了解 workflow_settings.yaml 属性，请参阅 GitHub 中的工作流设置配置参考文档。

您可以在 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 数据集区域。 如需详细了解 BigQuery 数据集位置，请参阅数据集位置。在此位置，Dataform 会处理您的代码并存储已执行的数据。此处理区域必须与您的 BigQuery 数据集所在的位置一致，但不必与 Dataform 代码库区域一致。
• assertionSchema：BigQuery 数据集，Dataform 在其中使用断言结果创建视图，默认称为 dataform_assertions。

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

准备工作

1. 创建代码库。

2. 在代码库中创建并初始化开发工作区。

所需的角色

如需获得配置 Dataform 设置所需的权限，请让您的管理员为您授予代码库的 Dataform Admin (roles/dataform.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

配置架构名称

如需配置架构名称，您需要修改 workflow_settings.yaml 文件中的 defaultDataset 和 defaultAssertionSchema 属性，或修改 dataform.json 文件中的 defaultSchema 和 assertionSchema 属性。

如需配置架构的名称，请按以下步骤操作：

workflow_settings.yaml

1. 在开发工作区中，点击 Files 窗格中的 workflow_settings.yaml 文件。

2. 修改 defaultDataset 和/或 defaultAssertionSchema 的值。

以下代码示例展示了 workflow_settings.yaml 文件中定义的自定义 defaultDataset 名称：

  ...
  defaultDataset: mytables
  ...

dataform.json

1. 在开发工作区中，点击 Files 窗格中的 dataform.json 文件。

2. 修改 defaultSchema 和/或 assertionSchema 的值。

以下代码示例显示了 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": {
     "YOUR_VARIABLE":"VALUE"
   }
   

   替换以下内容：

   • 将 YOUR_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

1. 前往您的 Dataform 开发工作区。
2. 在 Files 窗格中，选择 dataform.json 文件。

3. 输入以下代码段：

   "vars": {
     "YOUR_VARIABLE":"VALUE"
   }
   

   替换以下内容：

   • 将 YOUR_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 表定义文件添加编译变量，请按以下步骤操作：

1. 前往您的 Dataform 开发工作区。
2. 在 Files 窗格中，选择一个 SQLX 表定义文件。

3. 在该文件中，按以下格式输入 when 子句：

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

   替换以下内容：

   • 将 YOUR_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，请按以下步骤操作：

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 核心软件包迁移到 workflow_settings.yaml，请参阅管理 Dataform 核心软件包。

• 如需详细了解 Dataform 项目设置，请参阅 IProjectConfig 参考文档。