本页面介绍了如何修改 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
的属性
对象。
准备工作
所需的角色
如需获取配置 Dataform 设置所需的权限,
请让管理员向您授予
针对代码库的 Dataform Admin (roles/dataform.admin
) IAM 角色。
如需详细了解如何授予角色,请参阅管理访问权限。
配置架构名称
如需配置架构名称,您需要修改 defaultDataset
和
defaultAssertionSchema
个房源
workflow_settings.yaml
文件,或 defaultSchema
和 dataform.json
文件中的 assertionSchema
属性。
如需配置架构名称,请按以下步骤操作:
workflow_settings.yaml
在开发工作区的 Files 窗格中,点击
workflow_settings.yaml
文件。修改
defaultDataset
和/或defaultAssertionSchema
的值。
以下代码示例展示了在defaultDataset
workflow_settings.yaml
文件:
...
defaultDataset: mytables
...
dataform.json
在开发工作区的 Files 窗格中,点击
dataform.json
文件。修改
defaultSchema
和/或assertionSchema
的值。
以下代码示例展示了在defaultSchema
dataform.json
文件:
{
...
"defaultSchema": "mytables",
...
}
创建自定义编译变量
编译变量包含可通过编译进行修改的值 替换设置。
在 workflow_settings.yaml
中定义编译变量并将其添加到
选择表中,您可以在版本配置中修改其值,或
Dataform API 编译替换
有条件地执行表
如需详细了解如何使用 编译变量,请参阅 Dataform 中的代码生命周期简介。
要创建可在整个仓库中使用的编译变量,请按以下步骤操作: 请按以下步骤操作:
workflow_settings.yaml
- 转到 Dataform 开发工作区。
- 在 Files 窗格中,选择
workflow_settings.yaml
文件。 输入以下代码段:
"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
- 转到 Dataform 开发工作区。
- 在 Files 窗格中,选择
dataform.json
文件。 输入以下代码段:
"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 表定义文件,请执行以下操作: 请按以下步骤操作:
- 转到 Dataform 开发工作区。
- 在文件窗格中,选择一个 SQLX 表定义文件。
在该文件中,按以下格式输入
when
子句:${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}
替换以下内容:
- 将 YOUR_VARIABLE 替换为您的变量的名称,
例如
executionSetting
。 - 将 SET_VALUE 替换为变量的值;
例如
staging
。 - 将 CONDITION 替换为表的执行条件。
- 将 YOUR_VARIABLE 替换为您的变量的名称,
例如
以下代码示例展示了一个具有 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
,请按以下步骤操作:
在 Google Cloud 控制台中,前往 Dataform 页面。
选择一个代码库,然后选择一个工作区。
在文件窗格中,点击 addAdd, 然后点击创建文件。
在添加文件路径字段中,输入
workflow_settings.yaml
。点击创建文件。
在
workflow_settings.yaml
文件中,添加来自dataform.json
文件,映射到 YAML 格式。在 Files 窗格中,点击
dataform.json
旁边的 More 菜单。 然后点击删除。如需确认删除
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
参考文档。