配置 Dataform 工作流设置

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

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

代码库设置简介

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

从 Dataform core 3.0 开始， 默认情况下，系统会将工作流程设置 位于 workflow_settings.yaml 文件中。在早期版本的 Dataform Core 中， 工作流设置存储在 dataform.json 文件中。 Dataform 核心 3.0 workflow_settings.yaml 文件是 向后兼容 dataform.json。您可以继续使用 dataform.json，用于配置 Dataform 设置。

关于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 会创建名为 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!"
  )}

后续步骤