配置 Dataform 设置

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

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

代码库设置简介

每个 Dataform 代码库都包含一个唯一的 dataform.json 设置文件。该文件包含 Google Cloud 项目 ID 以及 Dataform 在 BigQuery 中发布资产的架构。

Dataform 使用默认设置，您可以通过修改 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：Dataform 在其中创建资产的 BigQuery 数据集，默认称为 dataform。
  • defaultLocation：您的默认 BigQuery 数据集区域。如需详细了解 BigQuery 数据集位置，请参阅数据集位置。Dataform 会在此位置处理代码并存储执行的数据。此处理区域必须与 BigQuery 数据集的位置相匹配，但无需与 Dataform 代码库区域匹配。
  • assertionSchema：BigQuery 数据集，其中 Dataform 使用断言结果创建视图，默认称为 dataform_assertions。

您可以将项目代码中定义的 dataform.json 属性作为 dataform.projectConfig 对象的属性进行访问。如需详细了解 dataform.projectConfig 对象，请参阅 IProjectConfig Dataform 核心参考文档。

以下代码示例展示了在视图的 SELECT 语句中调用的 dataform.projectConfig 对象：

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.warehouse === "bigquery",
    "warehouse is set to BigQuery!",
    "warehouse is not set to BigQuery!"
  )}

准备工作

  1. 创建代码库。

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

所需的角色

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

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

配置架构名称

此任务介绍了如何在 dataform.json 文件中配置 defaultSchema 和 assertionSchema 属性。

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

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

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

以下代码示例在 dataform.json 文件中显示了自定义 defaultSchema 名称：

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

创建自定义编译变量

编译变量包含值，您可以使用 在 Dataform API 请求中通过编译替换来修改这些值。

在 dataform.json 中定义编译变量并将其添加到选定的表后，您可以使用 中的 Dataform API 编译替换修改其值，以便有条件地执行表。

如需创建可跨代码库使用的编译变量，请按以下步骤操作：

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

  3. 输入以下代码段：

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

    请替换以下内容：

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

以下代码示例显示了 dataform.json 文件中设置为 myVariableValue 的 myVariableName 编译变量：

  {
    ...
    "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. 在 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!"
  )}

后续步骤