构建代码库中的代码

本文档介绍了在 Dataform 代码库的根目录 definitions 目录中构建 SQL 工作流文件以及为其命名的最佳实践。definitions 目录的推荐结构反映了 SQL 工作流的各个阶段。您可以根据自己的业务需求采用任何结构。

出于以下原因，您可能需要在 definitions 目录中构建 SQL 工作流代码：

  • 将团队指定为工作流程的选定部分，加强对代码库的协作。
  • 提高 SQL 工作流在组织变更时的可维护性。
  • 改善通过代码库进行导航的行为。
  • 提高代码库的可伸缩性。
  • 最大限度地减少团队的管理开销。

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

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

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

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

definitions 目录中的子目录的以下结构体体现了 SQL 工作流的关键阶段：

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

有关“sources”目标的最佳做法

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

在 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 创建数据源声明，请参阅使用 JavaScript 创建 Dataform SQL 工作流。

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

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

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

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

有关“intermediate”目标的最佳做法

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

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

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

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

有关“outputs”目标的最佳做法

outputs 子目录包含 SQL 工作流的最后阶段：根据转换后的数据创建用于业务用途的输出表。

在 outputs 目录中，存储计划在 Dataform 将表导出到 BigQuery 后用于其他进程或工具的表，例如报告或信息中心。outputs 目录中的表通常从 intermediate 表查询数据。

根据与营销业务相关的业务实体（例如营销、订单或分析）对 outputs 表进行分组。为每个商家实体指定一个子目录。

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

以下示例展示了包含两个业务实体的 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

后续步骤