本文档介绍了如何在 Dataform 中执行以下操作:
准备工作
在 Google Cloud 控制台中,进入 Dataform 页面。
选择或创建代码库。
选择或创建开发工作区。
可选:如需替换发布配置中的默认 Google Cloud 项目,请向您的 Dataform 服务账号授予对您计划使用的项目的访问权限。
所需的角色
如需获得完成本文档中任务所需的权限,请让管理员向您授予代码库的以下 IAM 角色:
-
Dataform Admin (
roles/dataform.admin
) -
Dataform Editor (
roles/dataform.editor
)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
Dataform 中的代码生命周期简介
本部分介绍了 Dataform 中的代码生命周期,以及在 Dataform 中配置编译和执行的方法。
Dataform 代码生命周期包括以下阶段:
- 开发
- 您在 Dataform 工作区中开发工作流。
- 编译
Dataform 会将工作区中的工作流代码实时编译为 SQL,从而创建可在 BigQuery 中执行的工作区编译结果。Dataform 会使用您在工作流设置文件中定义的设置来创建编译结果。
Dataform 编译是密封的,以确保编译一致性,这意味着相同的代码每次都会编译为相同的 SQL 编译结果。Dataform 会在无法访问互联网的沙盒环境中编译您的代码。编译期间无法执行任何其他操作(例如调用外部 API)。
- 执行
在工作流调用中,Dataform 会在 BigQuery 中执行工作区编译结果。
如需根据您的需求量身定制 Dataform 代码生命周期,您可以配置编译结果,以影响 Dataform 执行工作流的位置和方式。然后,您可以手动触发或安排执行操作,以影响 Dataform 执行整个工作流或其所选元素的时间。
配置 Dataform 编译的方法
默认情况下,Dataform 使用工作流设置文件中的设置来创建编译结果。您可以使用编译替换项替换默认设置,以创建自定义编译结果。然后,您可以手动触发自定义编译结果的执行,也可以安排执行。
Dataform 提供了以下用于配置编译结果的选项:
- 工作区编译替换
- 您可以配置适用于代码库中所有工作区的编译替换。您可以使用工作区编译替换来创建隔离的开发环境。
- 版本配置
- 您可以创建发布配置,以配置用于创建 Dataform 仓库编译结果的模板。然后,您可以创建工作流配置,以安排在所选版本配置中创建的编译结果的执行。
- Dataform API 编译替换项
- 您可以在终端中传递 Dataform API 请求,以使用编译替换项创建和执行单个编译结果。
配置工作区编译替换
借助工作区编译替换,您可以为 Dataform 代码库中的所有工作区创建编译替换。您可以为每个代码库创建一个工作区编译替换配置。
当您在包含工作区编译替换的代码库中在工作区中手动触发执行时,Dataform 会将这些替换项应用于工作区的编译结果。
您可以配置以下工作区编译替换:
- Dataform 执行工作区内容的 Google Cloud 项目
- 表前缀
- 架构后缀
您可以使用工作区编译替换来创建隔离的开发环境,方法是使用动态编译替换在 BigQuery 中隔离工作区编译结果。动态表前缀和架构后缀编译替换项包含 ${workspaceName}
变量。当您在工作区中触发执行时,Dataform 会将 ${workspaceName}
变量替换为当前工作区的名称,从而创建对该工作区而言唯一的编译替换项。
请注意,您无法安排使用工作区编译替换项创建的编译结果的执行。
创建版本配置
借助发布配置,您可以配置设置模板,以创建代码库的编译结果。
在版本配置中,您可以配置工作流设置、编译变量以及整个代码库的编译结果创建频率的编译替换。
在发布配置中,您可以配置以下编译替换项:
- Google Cloud 项目
- 表前缀
- 架构后缀
- 编译变量的值
您可以在 Dataform 代码库中创建多个发布配置,每个配置对应于开发生命周期的每个阶段,从而创建隔离的代码库编译结果。
然后,您可以创建工作流配置以安排所选版本配置中创建的编译结果的执行。
您还可以手动触发在所选发布配置中执行编译结果。
使用 Dataform API 编译替换项配置单个编译结果
通过在终端中传递 Dataform API 请求,您可以为单个编译结果配置编译替换项。
在 compilationResults.create
请求中,您可以创建 Dataform 工作区或指定 Git 提交的单个编译结果。
在 compilationResults.create
请求的 CodeCompilationConfig
对象中,您可以为编译请求配置编译替换项。
您可以配置以下 Dataform API 编译替换项:
- Google Cloud 项目
- 表前缀
- 架构后缀
- 编译变量的值
请注意,Dataform API 编译替换项适用于单个编译结果和单次执行。您无法使用它们来安排 Dataform 执行。
您可以在 workflowInvocations.create
请求中执行编译结果。
配置 Dataform 执行的方式
Dataform 提供了以下用于配置执行的选项:
- 在工作区中手动执行
- 您可以在 Dataform 工作区中手动触发工作流的即时执行,而无需遵循任何时间表。您可以在工作流中执行所选操作。
- 工作流配置
- 您可以安排在所选的发布配置中创建的编译结果的执行。您可以选择要执行的工作流操作,并设置执行频率和时区。
在工作区中触发即时执行
在 Dataform 工作区中,您可以手动触发工作区中工作流的即时执行,而无需遵循任何时间表。
您可以在工作区中手动执行工作流的以下元素:
如果您的代码库包含工作区编译替换,您可以查看 Dataform 将对工作区编译结果应用哪些编译替换。
创建工作流配置
借助工作流配置,您可以安排从所选版本配置中执行编译结果。您可以在 Dataform 代码库中创建多个工作流配置。
在工作流配置中,您可以配置以下执行设置:
- 应用的编译版本配置。
- 选择要执行的工作流操作。
- 执行时间表和时区。
您可以选择要执行的以下工作流操作:
- 所有操作
- 所选操作
- 与所选代码相关的操作
然后,在按计划执行工作流配置期间,Dataform 会将您从应用的编译结果中选择的操作部署到 BigQuery。
借助 Dataform 版本配置和工作流配置,您可以在 Dataform 中配置编译并安排执行作业,而无需依赖于其他服务。
生命周期资源的到期
Dataform 会存储特定时间段内的编译结果和工作流调用。
工作流调用的过期
工作流调用会在 90 天后或您手动删除它们后过期。
在工作流配置中,您可以查看该配置创建的最新工作流调用的列表。由工作流配置创建的工作流调用过期后,Dataform 会将该工作流调用从最近调用列表中移除。
编译结果的到期
编译结果的失效时间取决于它们是在开发工作区、发布配置中还是通过工作流调用创建的。
当您在 Dataform 工作区中开发工作流时,Dataform 会将您的代码实时编译为编译结果,以提供查询验证。以这种方式创建的编译结果会在 24 小时后过期。
在发布配置中,最新的编译结果会成为实时编译结果。新的编译结果会替换当前的实时编译结果。Dataform 会保留实时编译结果,直到其被新编译结果替换为止。替换的编译结果最长会在 24 小时后过期。
Dataform 会从版本配置的详细信息页面上的过往编译结果列表中移除已过期的编译结果。
Dataform 会在工作流调用的整个生命周期内保留由工作流调用创建的编译结果,最长可在工作流调用过期或被删除后 24 小时。
创建工作区编译替换
以下部分介绍了如何创建工作区编译替换项,以便在 BigQuery 中隔离从 Dataform 工作区创建的表和视图。您可以使用工作区编译替换项创建隔离的 Dataform 开发环境。
当您在 Dataform 工作区中开发工作流代码时,Dataform 会实时编译工作区中的代码,以创建工作区的编译结果。Dataform 使用工作流设置文件中定义的设置来创建工作区编译结果。然后,当您在工作区中触发执行时,Dataform 会在 BigQuery 中执行工作区编译结果。
如需替换为代码库中的所有工作区在工作流设置中设置的默认设置,您可以创建工作区编译替换。
借助工作区编译替换,您可以为代码库中的所有工作区替换以下设置:
- 项目
- Dataform 执行工作区编译结果的 Google Cloud 项目,在
workflow_settings.yaml
中设置为defaultProject
,在dataform.json
中设置为defaultDatabase
。 - 表前缀
- 添加到代码库中所有工作区的所有表名称的自定义前缀。
- 架构后缀
- 附加到表架构的自定义后缀。在
workflow_settings.yaml
中设置为defaultDataset
,在dataform.json
中设置为defaultSchema
,或在表的config
块中的schema
参数中设置。
如需创建隔离的开发环境,您可以使用唯一的编译替换来隔离工作区。您可以使用 ${workspaceName}
变量动态修改表前缀和架构后缀编译替换项。
当您在工作区中手动触发执行时,${workspaceName}
变量会将工作区的名称注入到工作区编译替换项中。
当您将 ${workspaceName}
设置为表前缀时,Dataform 会将工作区的名称添加到工作区中所有表的名称中。执行后,您可以在 BigQuery 中确定表来自哪个工作区。
当您将 ${workspaceName}
设置为架构后缀时,Dataform 会将工作区的名称附加到 defaultSchema
,从而创建专用于该工作区的自定义架构。执行后,您可以在 BigQuery 中找到专用架构中从特定工作区执行的所有表。
动态工作区编译替换示例
以下示例展示了应用于某个代码库的动态工作区编译替换项,该代码库包含以在该代码库中工作的开发者命名的工作区:Sasha
和 Kai
。
在此示例中,工作区编译替换的目标是为 Sasha 和 Kai 创建隔离的开发环境。
workflow_settings.yaml
中设置了以下默认设置:
defaultProject
:analytics
defaultDataset
:dataform
以下工作区编译替换会为代码库中的每个工作区创建动态表前缀和架构后缀:
- Google Cloud 项目 ID:
analytics_dev
- 表前缀:
${workspaceName}
- 架构后缀:
${workspaceName}
当 Sasha 在 Sasha
工作区中手动触发执行时,Dataform 会使用以下设置执行其内容:
- Google Cloud 项目:
analytics_dev
- 架构:
dataform_sasha
- 表名称:
sasha_name
,例如sasha_orders
当 Kai 在 Kai
工作区中手动触发执行时,Dataform 会使用以下设置执行其内容:
- Google Cloud 项目:
analytics_dev
- 架构:
dataform_kai
- 表名称:
kai_name
,例如kai_orders
创建工作区编译替换
如需创建 Dataform 工作区编译替换,请按以下步骤操作:
- 在代码库中,前往设置。
- 点击修改。
- 在工作区编译替换窗格的 Google Cloud 项目 ID 字段中,输入项目的 ID。
- 在表前缀字段中,输入所有表名称的前缀。
- 可选:如需为每个工作区创建唯一的动态表前缀,请输入
${workspaceName}
作为表前缀。
- 可选:如需为每个工作区创建唯一的动态表前缀,请输入
- 在架构后缀字段中,输入要附加到所创建表或视图的架构的后缀。
- 可选:如需为每个工作区创建唯一的动态架构后缀,请输入
${workspaceName}
作为表后缀。
- 可选:如需为每个工作区创建唯一的动态架构后缀,请输入
- 点击保存。
Dataform 会将工作区编译替换应用于您代码库中的所有工作区。
修改工作区编译替换
如需修改 Dataform 工作区编译替换,请按以下步骤操作:
- 在代码库中,前往设置。
- 点击修改。
- 修改工作区编译替换项,然后点击保存。
删除工作区编译替换
如需删除 Dataform 工作区编译替换项,请按以下步骤操作:
- 在代码库中,前往设置。
- 点击修改。
- 在工作区编译替换窗格中,点击清除全部,然后点击保存。
使用 Dataform API 配置编译替换项
本部分介绍了如何使用 Dataform API 创建和执行包含编译替换项的编译结果。
Dataform API 编译替换项简介
为了执行工作流,Dataform 会将您的代码编译为 SQL 以创建编译结果。然后,在工作流调用期间,Dataform 会在 BigQuery 中执行编译结果。
默认情况下,Dataform 使用工作流设置文件中的设置来创建编译结果。如需隔离在开发生命周期的不同阶段执行的数据,您可以使用编译替换来替换默认设置。
通过在终端中传递 Dataform API 请求,您可以使用编译替换项创建和执行单个编译结果。您可以创建工作区或所选 Git 提交的编译结果。
如需创建包含编译替换项的编译结果,您需要发出 Dataform API compilationResults.create
请求。在请求中,您需要指定来源(应为工作区或 Git 提交内容),以便 Dataform 编译到编译结果中。在 compilationResults.create
请求的 CodeCompilationConfig
对象中,您可以配置编译替换项。
然后,您可以在 Dataform API workflowInvocations.create
请求中执行创建的编译结果。
您可以使用 Dataform API 配置以下编译替换项:
- Google Cloud 项目
- Dataform 执行编译结果的项目,在
workflow_settings.yaml
文件中设置为defaultProject
属性,在dataform.json
文件中设置为defaultDatabase
属性。 - 表前缀
- 添加到编译结果中的所有表名称的自定义前缀。
- 架构后缀
- 附加到
workflow_settings.yaml
文件的defaultDataset
属性、dataform.json
文件的defaultSchema
属性或表的config
代码块中的schema
参数中定义的表架构的自定义后缀。 - 编译变量的值
- 要用于编译结果中的编译变量的值。您可以使用编译变量有条件地执行表。
您可以在 Google Cloud 控制台中配置工作区编译替换项,作为只能用于一个编译结果的 Dataform API 编译替换项的替代方案。
如需了解在 Dataform 中配置编译替换项的其他方法,请参阅代码生命周期简介。
设置编译结果来源
如需发出 Dataform API compilationResults.create
请求,您需要为编译结果指定来源。
您可以在 compilationResults.create
请求中将 Dataform 工作区或 Git 分支、Git 标记或 Git 提交 SHA 设置为来源。
将工作区设置为编译结果源
在
compilationResults.create
请求中,使用以下格式将所选 Dataform 工作区的路径填充到workspace
属性中:{ "workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME" }
替换以下内容:
- PROJECT_NAME:您的 Google Cloud 项目的名称。
- LOCATION:Dataform 代码库的位置,在工作流设置中设置。
- REPOSITORY_NAME:您的 Dataform 代码库的名称。
- WORKSPACE_NAME:您的 Dataform 工作区的名称。
以下代码示例展示了 compilationResults.create
请求中的 workspace
属性已设置为名为 "sales-test"
的工作区:
{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}
将 Git 提交内容设置为编译结果源
在
compilationResults.create
请求中,使用以下格式将所选的 Git 分支、标记或提交 SHA 填充gitCommitish
属性:{ "gitCommitish": "GIT_COMMITISH" }
将 GIT_COMMITISH 替换为编译结果的所选 Git 分支、Git 标记或 Git 提交 SHA。
以下代码示例展示了 compilationResults.create
请求中的 gitCommitish
属性已设为 "staging"
:
{
"gitCommitish": "staging"
}
替换默认项目
如需在与用于开发的项目不同的 Google Cloud 项目中创建预演版或生产版表,您可以在 Dataform API compilationResults.create
请求的 CodeCompilationConfig
对象中传递其他项目 ID。
在 compilationResults.create
请求中传递单独的默认项目 ID 会覆盖工作流设置文件中配置的默认项目 ID,但不会覆盖在各个表中配置的项目 ID。
如需替换默认项目 ID,请按以下格式将
defaultDatabase
属性设置为CodeCompilationConfig
对象中的所选项目 ID:{ "codeCompilationConfig": { "defaultDatabase": "PROJECT_NAME" } }
将 PROJECT_NAME 替换为您要为编译结果设置的项目 ID。
添加表前缀
如需从编译结果中快速识别表,您可以通过在 Dataform API compilationResults.create
请求的 CodeCompilationConfig
对象中传递表前缀,为编译结果中的所有表名称添加前缀。
如需添加表前缀,请按以下格式设置
CodeCompilationConfig
对象中的tablePrefix
属性:{ "codeCompilationConfig": { "tablePrefix": "PREFIX", } }
将 PREFIX 替换为要附加的前缀,例如
staging
。例如,如果表名称为
table_name
,Dataform 会创建名称为staging_table_name
的表。
附加架构后缀
如需分隔开发数据、预演数据和生产数据,您可以通过在 Dataform API compilationResults.create
请求的 CodeCompilationConfig
对象中传递架构后缀,将后缀附加到编译结果中的架构。
如需附加架构后缀,请按以下格式在
CodeCompilationConfig
对象中设置schemaSuffix
属性:{ "codeCompilationConfig": { "schemaSuffix": "SUFFIX", } }
将 SUFFIX 替换为您要附加的后缀,例如
_staging
。例如,如果
workflow_settings.yaml
文件中的defaultDataset
属性设置为dataform
,Dataform 会在dataform_staging
架构中创建表。
使用编译变量有条件地执行所选文件
如需仅在特定执行设置下执行所选表,您可以为该执行设置创建一个编译变量,然后在 Dataform API compilationResults.create
请求的 CodeCompilationConfig
对象中传递其值。
如需使用 Dataform API 在特定执行设置中有条件地执行表,请按以下步骤操作:
- 创建编译变量并将其添加到所选表中。
在 Dataform API 编译请求的
codeCompilationConfig
块中,按以下格式设置 YOUR_VARIABLE 和 VALUE 键值对:{ "codeCompilationConfig": { "vars": { "YOUR_VARIABLE": "VALUE" } } }
将 YOUR_VARIABLE 替换为变量的名称,例如
executionSetting
。将 VALUE 替换为满足所选表中设置的
when
条件的此编译结果的变量值。
以下代码示例展示了传递给 Dataform API 编译请求的 executionSetting
变量:
{
"gitCommitish": "staging",
"codeCompilationConfig": {
"vars": {
"executionSetting": "staging"
}
}
}
使用编译替换项执行编译结果
- 如需执行由
compilationResults.create
请求创建的编译结果,请在workflowInvocations.create
请求中传递compilationResults.create
请求返回的编译结果 ID。
以下代码示例展示了在 workflowInvocations.create
请求中传递的编译结果 ID:
{
"compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}
创建版本配置
以下部分介绍了如何在 Dataform 中创建发布配置,以配置可按计划执行的编译设置模板。您可以使用版本配置来配置执行环境,例如预演环境和生产环境。
如需在 BigQuery 中执行工作流,Dataform 会将 SQL 工作流代码编译为编译结果。当您在 Dataform 工作区中开发工作流时,系统会自动执行此过程。
借助版本配置,您可以自定义编译结果。您可以使用它们创建执行环境,例如预演环境。
版本配置设置
在版本配置中,您可以配置工作流设置的编译替换项、设置编译变量,以及设置创建编译结果的频率。
Dataform 版本配置包含以下编译设置:
- 发布设置
- 版本的 ID、编译结果的 Git Commitish 和创建编译结果的频率。频次是可选设置。如果设置,则最小频率为 1 小时。
- 编译替换
- 工作流设置中定义的 Google Cloud 项目、表前缀、架构后缀和编译变量的替换项。
版本配置的运作方式
Dataform 会按照指定的频率或在您触发编译时,根据版本配置创建编译结果。频率是可选设置,创建发布配置时无需填写。如果设置,最短频率为 1 小时。您可以在“版本配置详情”页面上手动触发编译,也可以使用 Dataform API releaseConfigs
方法触发编译。
在编译期间,Dataform 会从代码库的指定 Git 提交版本中拉取代码。然后,Dataform 会使用应用的编译替换项(如果有)编译代码,并创建编译结果。为发布配置创建的最新编译结果即为实时编译结果。
您可以在工作流配置中安排从发布配置执行编译结果。您还可以在任何时间表之外执行所选的发布配置。在工作流配置执行期间,Dataform 会执行所选版本配置中的实时编译结果。
创建版本配置
如需创建 Dataform 版本配置,请按以下步骤操作:
- 在代码库中,前往版本和时间安排。
- 在版本配置部分中,点击创建。
在创建发布配置窗格中,配置发布设置。
在版本 ID 字段中,输入版本配置的唯一 ID。
ID 只能包含数字、字母、连字符和下划线。
在 Git commitish 字段中,输入相应版本的 Git 分支或 Git 提交 SHA。
在未连接到远程仓库的数据表单仓库中,此值始终为
main
。可选:在频率列表中,选择创建编译结果的频率。
如果设置,最小频率为 1 小时。
可选:在编译替换项部分中,配置编译设置。
- 在 Google Cloud 项目 ID 字段中,输入您要存储编译结果的 Google Cloud 项目的 ID。
- 在架构后缀字段中,输入要附加到工作流设置中配置的架构的后缀。
- 在表前缀字段中,输入所有表名称的前缀。
可选:在编译变量部分中,设置编译变量。
- 点击添加变量。
- 在键字段中,输入编译变量。
- 在值字段中,输入编译变量的值。
- 如需添加其他编译变量,请点击添加变量。
点击创建。
如果您替换默认项目,请确保您的 Dataform 服务账号有权访问在发布配置中设置的项目。
例如,以下版本配置会每小时从 main
分支创建一个 production
编译结果,而不会进行任何编译替换:
- 版本 ID:
production
- Git 提交:
main
- 频率:每小时
- 无编译替换
查看版本配置的详细信息
您可以查看版本配置的以下详细信息:
- 发布设置
- Git Commitish
- 最新的编译结果时间戳
- Cron 时间表
- 编译替换
- 编译变量
- 实时编译结果
- 创建时间戳
- Git Commitish
- 提交 SHA
- 过往编译结果
如需查看版本配置的详细信息,请按以下步骤操作:
- 在代码库中,前往版本和时间安排。
- 选择一个版本配置。
- 在版本配置详细信息页面上,检查版本配置的详细信息。
已安排的编译结果表会显示版本配置自动创建的过往编译结果。
手动/API 编译结果表格会显示仓库中最新的 1,000 条编译结果中的手动创建或通过调用 Dataform API 创建的编译结果。
手动触发编译
如需根据所选的版本配置手动创建编译结果,请按以下步骤操作:
- 在代码库中,前往版本和时间安排。
- 选择一个版本配置。
- 在版本配置详情页面上,点击新建编译。
新创建的编译结果将成为该发布配置的实时结果。
手动编译结果会显示在版本配置详情页面的手动/API 编译结果表中。
触发发布配置的执行
如需触发对所选发布配置的动态编译结果的执行,并将其导出到 BigQuery,请按以下步骤操作:
- 在代码库中,前往版本和时间安排。
- 在版本配置部分,点击开始执行。
- 在执行手动工作流窗格的版本配置列表中,选择一个版本配置。
- 选择要执行的工作流操作:
- 如需执行整个工作流,请点击所有操作。
- 如需在工作流中执行所选操作,请点击选择操作,然后选择操作。
- 如需针对所选代码执行操作,请点击代码选择,然后选择代码。
- 可选:如需执行所选操作或代码及其依赖项,请选择包含依赖项选项。
- 可选:如需执行所选操作或代码及其依赖项,请选择包含依赖项选项。
可选:如需从头开始重新构建所有表,请选择运行并完全刷新选项。
如果不使用此选项,Dataform 会更新增量表,而不会从头重建这些表。
点击开始执行。
修改版本配置
如需修改版本配置,请按以下步骤操作:
- 在代码库中,前往版本和时间安排。
- 在要修改的版本配置旁边,点击 更多菜单,然后点击修改。
- 在修改发布配置窗格中,修改发布配置设置,然后点击保存。
删除版本配置
如需删除版本配置,请按以下步骤操作:
- 在代码库中,前往版本和时间安排。
- 在要删除的版本配置旁边,点击 更多菜单,然后点击删除。
- 在删除版本配置对话框中,点击删除。
后续步骤
- 如需了解 Dataform 中代码生命周期的最佳实践,请参阅管理代码生命周期。
- 如需了解如何在工作区中手动触发执行,请参阅触发执行。
- 如需了解如何创建工作流配置,请参阅使用工作流配置安排运行作业。
- 如需详细了解 Dataform API,请参阅 Dataform API。