配置编译

本文档介绍了如何在 Dataform 中执行以下操作:

准备工作

  1. 在 Google Cloud 控制台中,前往 Dataform 页面。

    前往 Dataform

  2. 选择或创建代码库

  3. 选择或创建开发工作区

  4. 可选:如需替换发布配置中的默认 Google Cloud 项目,请向您的 Dataform 服务账号授予对您计划使用的项目的访问权限

所需的角色

如需获得完成本文档中的任务所需的权限,请让您的管理员为您授予代码库的 Dataform Admin (roles/dataform.admin) IAM 角色。 如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限

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

如果启用了严格的 act-as 模式,您必须对工作流配置中使用相应版本配置的每个服务账号都拥有 iam.serviceAccounts.actAs 权限,才能更新 Dataform 代码库的版本配置的版本。此权限包含在 Service Account User (roles/iam.serviceAccountUser) 角色中。

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 会将这些替换应用于工作区的编译结果。

您可以配置以下工作区编译替换:

  • Google Cloud Dataform 在其中运行工作区内容的项目
  • 表前缀
  • 架构后缀

您可以使用工作区编译替换,通过使用动态编译替换在 BigQuery 中隔离工作区编译结果来创建隔离的开发环境。动态表前缀和架构后缀编译替换包含 ${workspaceName} 变量。当您在工作区中触发执行时,Dataform 会将 ${workspaceName} 变量替换为当前工作区的名称,从而创建特定于该工作区的编译替换。

请注意,您无法安排使用工作区编译替换创建的编译结果的执行。

创建发布配置

借助发布配置,您可以配置用于创建代码库编译结果的设置模板。

在发布配置中,您可以配置工作流设置、编译变量的编译替换,以及创建整个代码库的编译结果的频率。

在发布配置中,您可以配置以下编译替换项:

  • Google Cloud 项目
  • 表前缀
  • 架构后缀
  • 编译变量的值

您可以在 Dataform 代码库中创建多个发布配置,每个配置对应一个开发生命周期阶段,从而创建隔离的代码库编译结果。

然后,您可以创建工作流配置来安排所选版本配置中创建的编译结果的执行

您还可以手动触发所选发布配置中编译结果的执行

使用 Dataform API 编译替换项配置单个编译结果

通过在终端中传递 Dataform API 请求,您可以为单个编译结果配置编译替换项。

compilationResults.create 请求中,您可以创建 Dataform 工作区或指定 Git comittish 的单个编译结果。

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 在其中运行工作区编译结果的项目,在 workflow_settings.yaml 中设置为 defaultProject 或在 dataform.json 中设置为 defaultDatabase。 Google Cloud
表前缀
添加到代码库中所有工作区的所有表名称中的自定义前缀。
架构后缀
附加到表架构的自定义后缀。在 workflow_settings.yaml 中设置为 defaultDataset,在 dataform.json 中设置为 defaultSchema,或在表格的 config 块中的 schema 参数中设置为 defaultSchema

如需创建隔离的开发环境,您可以使用唯一的编译替换来隔离工作区。您可以使用 ${workspaceName} 变量动态修改表前缀和架构后缀编译替换。

当您在工作区中手动触发执行时,${workspaceName} 变量会将工作区的名称注入到工作区编译替换中。

当您将 ${workspaceName} 设置为表前缀时,Dataform 会将工作区的名称添加到工作区中所有表的名称中。执行后,您可以在 BigQuery 中确定表的来源工作区。

当您将 ${workspaceName} 设置为架构后缀时,Dataform 会将工作区的名称附加到 defaultSchema,从而创建一个专用于该工作区的自定义架构。执行后,您可以在 BigQuery 中找到专用架构中从特定工作区运行的所有表。

动态工作区编译替换示例

以下示例展示了应用于包含以开发者命名的工作区(例如 SashaKai)的仓库的动态工作区编译替换项。

此示例中工作区编译替换的目标是为 Sasha 和 Kai 创建隔离的开发环境。

workflow_settings.yaml 中设置了以下默认设置:

  • defaultProject:analytics
  • defaultDatasetdataform

以下工作区编译替换会为代码库中的每个工作区创建动态表前缀和架构后缀:

  • Google Cloud 项目 IDanalytics_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 工作区编译替换,请按以下步骤操作:

  1. 在代码库中,前往设置
  2. 点击修改
  3. 工作区编译替换窗格的 Google Cloud 项目 ID 字段中,输入相应项目的 ID。
  4. 表前缀字段中,输入所有表名称的前缀。
    1. 可选:如需创建每个工作区独有的动态表前缀,请输入 ${workspaceName} 作为表前缀。
  5. 架构后缀字段中,输入要附加到所创建表或视图的架构的后缀。
    1. 可选:如需创建每个工作区独有的动态架构后缀,请输入 ${workspaceName} 作为表后缀。
  6. 点击保存

Dataform 会将工作区编译替换应用于您代码库中的所有工作区。

修改工作区编译替换

如需修改 Dataform 工作区编译替换,请按以下步骤操作:

  1. 在代码库中,前往设置
  2. 点击修改
  3. 修改工作区编译替换,然后点击保存

删除工作区编译替换

如需删除 Dataform 工作区编译替换,请按以下步骤操作:

  1. 在代码库中,前往设置
  2. 点击修改
  3. 工作区编译替换窗格中,点击全部清除,然后点击保存

使用 Dataform API 配置编译替换项

本部分介绍了如何使用 Dataform API 创建和运行具有编译替换项的编译结果。

关于 Dataform API 编译替换项

为了运行工作流,Dataform 会将您的代码编译为 SQL,以创建编译结果。 然后,在工作流调用期间,Dataform 会在 BigQuery 中运行编译结果。

默认情况下,Dataform 使用工作流设置文件中的设置来创建编译结果。如需隔离在开发生命周期的不同阶段运行的数据,您可以使用编译替换来替换默认设置。

通过在终端中传递 Dataform API 请求,您可以创建并运行具有编译替换的单个编译结果。您可以创建工作区或所选 Git 提交对象的编译结果。

如需创建具有编译替换项的编译结果,您需要发出 Dataform API compilationResults.create 请求。在请求中,您需要指定一个来源(应该是工作区或 Git commitish),以便 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 参数。
编译变量的值
要在编译结果中使用的编译变量的值。您可以使用编译变量有条件地运行表格。

除了只能用于一个编译结果的 Dataform API 编译替换项之外,您还可以在 Google Cloud 控制台中配置工作区编译替换项

如需了解在 Dataform 中配置编译替换的其他方法,请参阅 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 commitish 设置为编译结果来源

  • 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 在特定执行设置中有条件地运行表,请按以下步骤操作:

  1. 创建编译变量并将其添加到所选表格
  2. Dataform API 编译请求的 codeCompilationConfig 块中,以以下格式设置 YOUR_VARIABLEVALUE 键值对:

    {
      "codeCompilationConfig": {
        "vars": {
          "YOUR_VARIABLE": "VALUE"
        }
      }
    }
    
  3. YOUR_VARIABLE 替换为您的变量名称,例如 executionSetting

  4. VALUE 替换为满足所选表格中设置的 when 条件的相应编译结果的变量值。

以下代码示例展示了传递给 Dataform API 编译请求的 executionSetting 变量:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

运行具有编译替换项的编译结果

以下代码示例展示了在 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 commitish 中拉取代码。然后,Dataform 会使用已应用的编译替换项(如果有)编译代码,并创建编译结果。为发布配置创建的最新编译结果是实时编译结果。

您可以在工作流配置中安排发布配置的编译结果的执行时间。 您还可以在任何时间表之外运行所选的发布配置。在执行工作流配置期间,Dataform 会运行所选版本配置中的实时编译结果。

创建版本配置

如需创建 Dataform 发布配置,请按以下步骤操作:

  1. 在代码库中,前往发布和安排
  2. 发布配置部分中,点击创建
  3. 创建发布配置窗格中,配置发布设置。

    1. 发布 ID 字段中,输入发布配置的唯一 ID。

      ID 只能包含数字、字母、连字符和下划线。

    2. Git commitish 字段中,输入相应版本的 Git 分支或 Git 提交 SHA。

      在未连接到远程代码库的 Dataform 代码库中,该值始终为 main

    3. 可选:在频次字段中,选择生成汇总结果的频次。

      如果设置了此属性,则最低频率为 1 小时。

      如需停用自动发布,请将频率字段留空。

  4. 可选:在编译替换项部分中,配置编译设置。

    1. Google Cloud 项目 ID 字段中,输入您要存储编译结果的Google Cloud 项目的 ID。
    2. 架构后缀字段中,输入要附加到工作流设置中配置的架构的后缀。
    3. 表前缀字段中,输入所有表名称的前缀。
  5. 可选:在编译变量部分中,设置编译变量。

    1. 点击添加变量
    2. 字段中,输入编译变量。
    3. 字段中,输入编译变量的值。
    4. 如需添加其他编译变量,请点击添加变量
  6. 点击创建

如果您替换默认项目,请确保 Dataform 服务账号有权访问发布配置中设置的项目。

例如,以下发布配置每小时从 main 分支创建一次 production 编译结果,没有任何编译替换项:

  • 发布 IDproduction
  • Git commitishmain
  • 频率:每小时
  • 无编译替换

查看发布配置的详细信息

您可以查看发布配置的以下详细信息:

  • 发布版本设置
    • Git Commitish
    • 最新编译结果时间戳
    • Cron 时间表
    • 编译替换
    • 编译变量
  • 实时编译结果
    • 创建时间戳
    • Git Commitish
    • 提交 SHA
  • 过去的编译结果

如需查看发布配置的详细信息,请按以下步骤操作:

  1. 在代码库中,前往发布和安排
  2. 选择发布配置。
  3. 发布配置详细信息页面上,检查发布配置的详细信息。

已安排的编译结果表会显示版本配置自动创建的过往编译结果。

手动/API 编译结果表会显示手动创建或通过调用 Dataform API 创建的编译结果,这些结果是代码库中最新的 1,000 个编译结果。

手动触发编译

如需根据所选发布配置手动创建编译结果,请按以下步骤操作:

  1. 在代码库中,前往发布和安排
  2. 选择发布配置。
  3. 发布配置详情页面上,点击新编译版本

如果您使用的是界面,则新编译的结果会自动发布到您的发布配置中。如果您使用的是 API,则必须从发布配置中创建新的编译结果,然后更新发布配置,以使用此新值设置 releaseCompilationResult 字段。

手动编译结果会显示在发布配置详情页面上的手动/API 编译结果表中。

触发执行版本配置

如需触发将所选发布配置中的实时编译结果执行到 BigQuery,请按以下步骤操作:

  1. 在代码库中,前往发布和安排
  2. 版本配置部分,点击开始执行
  3. 执行手动工作流窗格的发布配置列表中,选择一个发布配置。
  4. 选择要运行的工作流操作:
    1. 如需运行整个工作流,请点击所有操作
    2. 如需运行工作流中的所选操作,请点击 Selection of actions,然后选择操作。
    3. 如需使用所选标记运行操作,请点击选择标记,然后选择标记。
  5. 可选:如需运行所选操作或代码及其依赖项,请选择包含依赖项选项。
  6. 可选:如需运行所选操作或代码及其依赖项,请选择包含依赖项选项。
  7. 可选:如需从头开始重建所有表格,请选择以完全刷新模式运行选项。

    如果没有此选项,Dataform 会更新增量表,而不会从头开始重建这些表。

  8. 点击开始执行

修改发布配置

如需修改发布配置,请按以下步骤操作:

  1. 在代码库中,前往发布和安排
  2. 在要修改的版本配置旁边,点击 更多菜单,然后点击修改
  3. 修改发布配置窗格中,修改发布配置设置,然后点击保存

删除版本配置

如需删除发布配置,请按照以下步骤操作:

  1. 在代码库中,前往发布和安排
  2. 在要删除的版本配置旁边,点击 更多菜单,然后点击删除
  3. 删除版本配置对话框中,点击删除

后续步骤