代码库最佳实践

本文档介绍了 Dataform 代码库的以下信息：

Dataform 中代码库最佳实践概览

本部分简要介绍了在 Dataform 中管理代码库大小、代码库结构和代码生命周期的最佳实践。

代码库大小方面的最佳实践

代码库大小会影响 Dataform 的多方面开发，例如：

  • 协作
  • 代码库可读性
  • 开发流程
  • 工作流编译
  • 执行工作流

Dataform 会对编译资源强制执行 API 配额和限制。代码库大小过大可能会导致您的代码库超出这些配额和限制。这可能会导致工作流编译和执行失败。

为降低此风险，我们建议拆分大型代码库。拆分大型代码库时，您需要将一个大型工作流拆分为多个较小的工作流，这些工作流存储在不同的代码库中，并通过跨代码库依赖项相连接。

通过这种方法，您可以遵守 Dataform 配额和限制、实现精细的流程和权限，并提高代码库的可读性和协作能力。不过，与管理单个代码库相比，管理分屏代码库可能更具挑战性。

如需详细了解 Dataform 中代码库大小的影响，请参阅代码库大小概览。如需详细了解拆分代码库的最佳实践，请参阅拆分代码库。

代码库结构的最佳实践

我们建议您在 definitions 目录中构建文件结构，以反映工作流的各个阶段。请注意，您可以采用最符合您需求的自定义结构。

以下 definitions 子目录的推荐结构反映了大多数工作流程的主要阶段：

  • sources，用于存储数据源声明。
  • intermediate，用于存储数据转换逻辑。
  • output，用于存储输出表的定义。
  • extras（可选），用于存储其他文件。

Dataform 中的所有文件的名称都必须符合 BigQuery 表命名准则。我们建议 Dataform 代码库中 definitions 目录中的文件名反映子目录结构。

如需详细了解在代码库中设置文件结构和命名文件的最佳实践，请参阅在代码库中设置代码结构。

代码生命周期最佳实践

Dataform 中的默认代码生命周期包括以下阶段：

  • 在 Dataform 工作区中开发工作流代码。

    您可以使用 Dataform 核心或仅使用 JavaScript 进行开发。

  • 使用工作流设置文件中的设置将代码编译为编译结果。

    您可以使用版本配置和工作区编译替换配置自定义编译结果。

    借助版本配置，您可以配置整个代码库的自定义编译结果。您稍后可以在工作流配置中安排其执行。

    借助工作区编译替换，您可以为代码库中的所有工作区配置编译替换，从而为每个工作区创建自定义编译结果。

  • 在 BigQuery 中执行编译结果。

    您可以使用工作流配置安排执行作业或代码库编译结果。

如需在 Dataform 中管理代码生命周期，您可以创建开发环境、预演环境和生产环境等执行环境。

如需详细了解 Dataform 中的代码生命周期，请参阅 Dataform 中的代码生命周期简介。

您可以选择将执行环境保存在单个代码库中，也可以保存在多个代码库中。

单个代码库中的执行环境

您可以使用工作区编译替换和版本配置，在单个 Dataform 仓库中创建隔离的执行环境，例如开发环境、预演环境和生产环境。

您可以通过以下方式创建隔离的执行环境：

  • 按架构拆分开发环境表和生产环境表。
  • 按架构和 Google Cloud 项目拆分开发和生产表。
  • 按项目拆分开发、预演和生产表。 Google Cloud

然后，您可以使用工作流配置在预演环境和生产环境中安排执行。我们建议您在开发环境中手动触发执行。

如需详细了解在 Dataform 中管理代码生命周期的最佳实践，请参阅管理代码生命周期。

多个代码库中的代码生命周期

如需根据代码生命周期的每个阶段量身定制 Identity and Access Management (IAM) 权限，您可以创建代码库的多个副本，并将其存储在不同的 Google Cloud 项目中。

每个 Google Cloud 项目都充当一个执行环境，与代码生命周期的某个阶段相对应，例如开发和生产。

在此方法中，我们建议您在所有项目中保持代码库的一致性。如需自定义代码库的每个副本中的编译和执行，请使用工作区编译替换、版本配置和工作流配置。

代码库大小概览

本部分将帮助您了解代码库大小如何影响工作流开发和 Dataform 编译资源用量，以及如何估算代码库的编译资源用量。

Dataform 中的代码库大小简介

代码库的大小会影响 Dataform 中以下方面的开发：

  • 协作。多个协作者共同处理一个大型代码库可能会导致拉取请求数量过多，从而增加合并冲突的风险。

  • 代码库可读性。如果单个代码库中用于构成工作流的文件数量较多，则可能会导致在代码库中导航时遇到困难。

  • 开发流程。单个代码库中大型工作流的某些部分可能需要自定义权限或流程（例如调度），这些权限或流程与应用于工作流其余部分的权限和流程不同。代码库大小过大，因此很难根据工作流的特定领域量身定制开发流程。

  • 工作流编译。Dataform 会对编译资源实施用量限制。代码库大小过大可能会导致超出这些限制，从而导致编译失败。

  • 工作流执行。在执行期间，Dataform 会在您的工作区内执行代码库代码，并将资产部署到 BigQuery。代码库越大，Dataform 执行它所需的时间就越长。

如果代码库的大小对您在 Dataform 中的开发有负面影响，您可以将代码库拆分为多个较小的代码库。

关于代码库编译资源限制

在开发期间，Dataform 会编译工作区中的所有代码库代码，以生成代码库中工作流的表示法。这称为编译结果。Dataform 会对编译资源强制执行用量限制。

您的代码库可能会因以下原因超出使用量上限：

  • 代码库代码中存在无限循环 bug。
  • 代码库代码中存在内存泄露 bug。
  • 代码库大小较大，大约超过 1, 000 项工作流操作。

如需详细了解编译资源的使用限制，请参阅 Dataform 编译资源限制。

估算代码库的编译资源用量

您可以估算代码库的以下编译资源用量：

  • CPU 时间用量。
  • 在代码库中定义的生成的操作图的序列化数据总大小上限。

如需大致了解代码库编译的当前编译 CPU 时间用量，您可以在本地 Linux 或 macOS 机器上对 Dataform 工作流的编译进行计时。

  • 如需对工作流的编译时间进行计时，请在代码库中按照以下格式执行 Dataform CLI 命令 dataform compile：

    time dataform compile

    以下代码示例展示了执行 time dataform compile 命令的结果：

    real    0m3.480s
user    0m1.828s
sys     0m0.260s

您可以将 real 结果视为代码库编译所用 CPU 时间的粗略指标。

如需大致了解在代码库中生成的操作图的总大小，您可以将图的输出写入 JSON 文件。您可以将未压缩 JSON 文件的大小视为图表总大小的大致指标。

  • 如需将工作流的已编译图的输出写入 JSON 文件，请在代码库中执行以下 Dataform CLI 命令：

    dataform compile --json > graph.json

拆分代码库

本部分介绍了拆分 Dataform 代码库和管理跨代码库依赖项的策略。

仓库是 Dataform 中的核心单元。代码库用于存储构成工作流的所有 SQLX 和 JavaScript 文件，以及 Dataform 配置文件和软件包。您可以将工作流存储在单个代码库中，也可以在多个代码库之间拆分工作流。

在 Dataform 中拆分代码库具有以下优势：

  • 遵守 Dataform 对编译资源使用量的限制。将大型工作流拆分为多个较小的代码库有助于降低超出 Dataform 对编译资源的限制的风险。
  • 精细化流程。您可以为工作流的每个分块片段及其开发团队单独设置流程（例如持续集成 [CI] 规则）。
  • 细化权限。您可以为工作流的每个分屏 fragment 及其开发团队分别设置权限，以增强工作流的整体安全性。
  • 尽可能减少在工作流的每个分屏 fragment 上协作的协作者数量，从而改进协作。
  • 提高了代码库的可读性。将构成大型工作流的文件拆分到多个代码库中，比一次浏览整个工作流更容易分别浏览每个代码库。
  • 与执行整个工作流相比，加快工作流的每个分块片段的工作流执行速度。

在 Dataform 中拆分代码库有以下缺点：

  • 每个 Dataform 代码库及其对应的 Git 代码库所需的自定义持续集成和持续开发 (CI/CD) 配置。
  • 每个 Dataform 代码库及其对应的 Git 代码库所需的自定义调度配置。
  • 难以管理存储在多个代码库中的工作流对象之间的依赖项。
  • 缺少对分布在多个代码库之间的 SQL 工作流的全面有向无环图 (DAG) 可视化。在每个代码库中，生成的 DAG 仅代表完整工作流的一部分。

拆分代码库的策略

拆分代码库时，您需要将构成父 SQL 工作流的文件划分为存储在单独 Dataform 代码库中的较小子工作流。

您可以选择通过以下任一方式拆分代码库：

  • 每个开发团队一个代码库。
  • 每个领域一个代码库，例如销售、营销或物流。
  • 一个中央存储库，每个网域一个存储库，其中存储库使用中央存储库的内容作为数据源。

如需将父级工作流存储在第三方 Git 托管平台中，您需要将包含子级工作流的每个单独代码库分别连接到专用的第三方 Git 代码库。

管理跨仓库依赖项

拆分代码库的最有效方法是将父 SQL 工作流分为自包含的子工作流，从而创建独立的代码库。独立仓库不会将其他仓库的内容用作数据源。此方法无需管理跨仓库依赖项。

如果无法避免跨仓库依赖项，您可以通过将一个仓库拆分为一系列仓库来管理它们，其中一个仓库依赖于其前身，并是其后继仓库的数据源。代码库及其依赖项的继承必须最能反映父级工作流的结构。

您可以使用 Dataform 数据源声明在仓库之间创建依赖项。您可以将其他 Dataform 仓库中的 BigQuery 表类型声明为所编辑仓库中的数据源。声明数据源后，您可以像引用任何其他 Dataform 工作流操作一样引用它，并使用它来开发工作流。

在具有跨仓库依赖项的仓库之间安排工作流分块的执行时，您必须按照跨仓库依赖项的顺序逐个执行仓库。

我们建议避免将代码库拆分为包含双向依赖项的一组代码库。当某个仓库是另一个仓库的数据源，同时也使用该仓库作为数据源时，就会出现仓库之间的双向依赖关系。存储库之间的双向依赖关系会使父级工作流的调度和执行以及开发流程变得复杂。

在代码库中构建代码结构

本部分介绍了在 Dataform 代码库的根 definitions 目录中构建和命名工作流文件的最佳实践。definitions 目录的推荐结构反映了工作流的各个阶段。您可以采用任何符合业务需求的结构。

您可能希望在 definitions 目录中构建工作流代码，原因如下：

  • 通过将团队指定为工作流的特定部分，改善代码库方面的协作。
  • 提高工作流的可维护性，以应对组织变更。
  • 改进代码库导航功能。
  • 提高代码库的可伸缩性。
  • 最大限度地减少团队的管理开销。

Dataform 代码库中的根 definitions 目录包含用于创建工作流元素的代码。您可以将 definitions 目录中的文件整理成反映工作流结构的目录结构。

开发工作流时，您需要声明源表并对其进行转换，以创建可用于业务或分析用途的输出表。

您可以区分工作流的三个关键阶段：

  1. 声明数据源。
  2. 源数据的转换。
  3. 转换后的源数据的输出表定义。

definitions 目录中的以下子目录结构反映了工作流的关键阶段：

sources
数据源声明和源数据的基本转换（例如过滤）。
intermediate
在您使用转换后的数据定义 outputs 表之前，从 sources 读取数据并转换数据的表和操作。表在 Dataform 将其执行到 BigQuery 后，通常不会再向其他进程或工具（例如商业智能 [BI] 工具）公开。
outputs
Dataform 在 BigQuery 中执行流程或工具（例如 BI）后，这些流程或工具所使用的表的定义。
extra
工作流主流水线之外的文件，例如包含为进一步使用（例如机器学习）准备的工作流数据的文件。可选的自定义子目录。

sources 最佳实践

sources 子目录包含工作流的第一阶段：声明和基本转换源数据。

在 sources 子目录中，存储用于过滤、分类、转换或重命名列的数据源声明和表。

避免存储将来自多个来源的数据组合在一起的表。

转换存储在 intermediate 子目录中的表中的 sources 数据。

如果您声明来自多个广告资源池（例如 Google Ads 或 Google Analytics [分析]）的数据源，请为每个广告资源池专门创建一个子目录。

以下示例展示了包含两个来源池的 sources 子目录结构：

definitions/
    sources/
        google_ads/
            google_ads_filtered.sqlx
            google_ads_criteria_metrics.sqlx
            google_ads_criteria_metrics_filtered.sqlx
            google_ads_labels.sqlx
            google_ads_labels_filtered.sqlx
        google_analytics/
            google_analytics_users.sqlx
            google_analytics_users_filtered.sqlx
            google_analytics_sessions.sqlx

如果您在同一架构中声明多个数据源表，则可以将其声明合并到单个 JavaScript 文件中。

如需详细了解如何使用 JavaScript 创建数据源声明，请参阅使用 JavaScript 创建 Dataform 工作流。

以下代码示例展示了在一个 JavaScript 文件中声明的单个架构中的多个数据源：

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

为了防止数据源更改影响您的工作流，您可以为每个数据源声明（例如 analytics_users_filtered.sqlx）创建一个视图。该视图可以包含对源数据的基本过滤和格式设置。将视图存储在 sources 子目录中。

然后，在创建 intermediate 或 outputs 表时，请引用视图，而不是原始源表。通过这种方法，您可以测试源表。如果源表发生更改，您可以修改其视图，例如通过添加过滤条件或重新转换数据。

intermediate 最佳实践

intermediate 子目录包含工作流程的第二阶段：对一个或多个来源的源数据进行转换和汇总。

在 intermediate 子目录中，存储用于对 sources 子目录中一个或多个来源的源数据进行重大转换的文件，例如用于联接数据的表。intermediate 子目录中的表通常会从源表或其他 intermediate 表中查询数据。

使用 intermediate 表创建 outputs 表。通常，在 Dataform 将 intermediate 表格执行到 BigQuery 后，这些表格不会用于其他用途（例如数据分析）。您可以将 intermediate 表视为用于创建输出表的数据转换逻辑。

我们建议您记录和测试所有 intermediate 表。

outputs 最佳实践

outputs 子目录包含工作流的最后一阶段：根据转换后的数据创建输出表以满足业务需求。

在 outputs 目录中，存储您计划在 Dataform 将其执行到 BigQuery 后在其他流程或工具中使用的表（例如报告或信息中心）。outputs 目录中的表通常会从 intermediate 表中查询数据。

按 outputs 表所关联的业务实体（例如营销、订单或分析）对 outputs 表进行分组。为每个企业实体分配一个子目录。

如需在 BigQuery 中单独存储输出表，您可以为输出表配置专用架构。如需了解如何配置表架构，请参阅替换表设置。

以下示例展示了包含 sales 和 marketing 商家实体的 outputs 子目录结构：

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

我们建议您记录和测试所有 outputs 表。

命名策略

Dataform 中的所有文件的名称都必须符合 BigQuery 表命名准则。

我们建议 Dataform 仓库中 definitions 目录中的文件名反映子目录结构。

在 sources 子目录中，文件名应指向与文件相关的源代码。将来源的名称添加为文件名的前缀，例如 analytics_filtered.sqlx

在 intermediate 子目录中，文件名应标识子目录，以便协作者能够清晰区分 intermediate 文件。选择一个唯一的前缀，并仅将其应用于 intermediate 目录中的文件，例如 stg_ads_concept.sqlx。

在 outputs 子目录中，文件名应简洁明了，例如 orders.sqlx。如果您在不同的实体子目录中有名称相同的 outputs 表，请添加用于标识实体的前缀，例如 sales_revenue.sqlx 或 ads_revenue.sqlx。

以下示例展示了 definitions 目录内的子目录结构，其中文件名符合建议的命名策略：

definitions/
    sources/
        google_analytics.sqlx
        google_analytics_filtered.sqlx
    intermediate/
        stg_analytics_concept.sqlx
    outputs/
        customers.sqlx
        sales/
            sales.sqlx
            sales_revenue.sqlx
        ads/
            campaigns.sqlx
            ads_revenue.sqlx

后续步骤