配置 Dataform 工作流设置

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

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

代码库设置简介

每个 Dataform 代码库都包含唯一的工作流设置文件。该文件包含 Google Cloud 项目 ID 以及 Dataform 在 BigQuery 中发布资源时所采用的架构。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

Dataform core 3.0 中引入的 workflow_settings.yaml 文件以 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：一个指针，指向 Dataform 在其中创建资产的 BigQuery。
  • defaultDatabase：您的 BigQuery Google Cloud 项目 ID。
  • defaultSchema：Dataform 在其中创建资产的 BigQuery 数据集，默认情况下名为 dataform。
  • 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 文件中设置为 myVariableValue 的 myVariableName 编译变量：

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

{
  ...
  "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. 在文件窗格中，选择一个 SQLX 表定义文件。

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

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

    请替换以下内容：

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

以下代码示例展示了一个表定义 SQLX 文件，其中包含 when 子句和用于在暂存执行设置中执行 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!"
  )}

后续步骤