配置 Dataform 工作流设置

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

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

代码库设置简介

每个 Dataform 代码库都包含唯一的工作流 设置文件。该文件包含 Google Cloud 项目 ID 和 。 Dataform 使用默认设置 您可以替换该值 修改设置文件。

从 Dataform core 3.0.0 开始， 默认情况下，工作流设置存储在 Workflow_settings.yaml 文件中。 在早期版本的 Dataform Core 中， 工作流设置存储在 dataform.json 文件中。 Dataform 核心 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

在上述代码示例中，键值对描述如下：

• defaultProject：您的 BigQuery Google Cloud 项目 ID。
• defaultDataset：该 BigQuery 数据集 默认情况下，Dataform 会创建名为 dataform 的资源。
• defaultLocation：您的默认 BigQuery 数据集区域。 如需详细了解 BigQuery 数据集位置， 请参阅数据集位置 在此位置，Dataform 会处理您的代码，并将 已执行数据。此处理区域必须与相应位置一致 数据，但不需要与 Dataform 代码库区域
• defaultAssertionDataset：该 BigQuery 数据集 Dataform 创建包含断言结果的视图，称为 默认为 dataform_assertions。

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

您可以在以下位置访问 workflow_settings.yaml 中定义的属性： Dataform 代码作为 dataform.projectConfig 对象。

以下是从 workflow_settings.yaml 选项到可访问代码的映射 dataform.projectConfig 个选项适用：

• defaultProject =>defaultDatabase。
• defaultDataset =>defaultSchema。
• defaultAssertionDataset =>assertionSchema。
• projectSuffix =>databaseSuffix。
• datasetSuffix =>schemaSuffix。
• namePrefix =>tablePrefix。

以下代码示例显示了在dataform.projectConfig 视图中的 SELECT 语句：

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

关于dataform.json

dataform.json 文件用于存储 Dataform 工作流设置 采用 JSON 格式。

以下代码示例展示了一个示例 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：该 BigQuery 数据集 Dataform 会创建资产。
• defaultLocation：您的默认 BigQuery 数据集区域。 如需详细了解 BigQuery 数据集位置， 请参阅数据集位置。 在此位置，Dataform 会处理您的代码，并将 已执行数据。此处理区域必须与相应位置一致 数据，但不需要与 Dataform 代码库区域
• assertionSchema：该 BigQuery 数据集 Dataform 创建包含断言结果的视图，称为 默认为 dataform_assertions。

您可以在项目代码中访问 dataform.json 中定义的属性，如下所示： dataform.projectConfig 的属性 对象。

准备工作

1. 创建代码库。

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

所需的角色

如需获取配置 Dataform 设置所需的权限， 请让管理员向您授予 针对代码库的 Dataform Admin (roles/dataform.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理访问权限。

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

配置架构名称

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

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

workflow_settings.yaml

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

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

以下代码示例展示了在defaultDataset workflow_settings.yaml 文件：

  ...
  defaultDataset: mytables
  ...

dataform.json

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

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

以下代码示例展示了在defaultSchema dataform.json 文件：

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

创建自定义编译变量

编译变量包含可通过编译进行修改的值 替换设置。

在 workflow_settings.yaml 中定义编译变量并将其添加到 选择表中，您可以在版本配置中修改其值，或 Dataform API 编译替换 有条件地执行表

如需详细了解如何使用 编译变量，请参阅 Dataform 中的代码生命周期简介。

要创建可在整个仓库中使用的编译变量，请按以下步骤操作： 请按以下步骤操作：

workflow_settings.yaml

1. 转到 Dataform 开发工作区。
2. 在 Files 窗格中，选择 workflow_settings.yaml 文件。

3. 输入以下代码段：

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

   替换以下内容：

   • 将 YOUR_VARIABLE 替换为变量的名称。
   • 将 VALUE 替换为编译变量的默认值。

以下代码示例显示了 myVariableName 编译变量集 添加到 workflow_settings.yaml 文件中的 myVariableValue：

...
vars:
  myVariableName: myVariableValue
...

以下代码示例显示了包含workflow_settings.yaml 将 executionSetting 编译变量设置为 dev：

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 替换为编译变量的默认值。

以下代码示例显示了 myVariableName 编译变量集 添加到 dataform.json 文件中的 myVariableValue：

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

以下代码示例显示了包含dataform.json 将 executionSetting 编译变量设置为 dev：

{
"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.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}
   

   替换以下内容：

   • 将 YOUR_VARIABLE 替换为您的变量的名称， 例如 executionSetting。
   • 将 SET_VALUE 替换为变量的值； 例如 staging。
   • 将 CONDITION 替换为表的执行条件。

以下代码示例展示了一个具有 when 的表定义 SQLX 文件 子句和 executionSetting 变量，该变量会执行系统中 10% 的数据 预演执行设置：

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

以下代码示例显示了一个包含 when 的视图定义 SQLX 文件 子句和 myVariableName 变量：

  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. 在文件窗格中，点击 addAdd, 然后点击创建文件。

4. 在添加文件路径字段中，输入 workflow_settings.yaml。

5. 点击创建文件。

6. 在 workflow_settings.yaml 文件中，添加来自 dataform.json 文件，映射到 YAML 格式。

7. 在 Files 窗格中，点击 dataform.json 旁边的 More 菜单。 然后点击删除。

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 参考文档。