本文档介绍了在 Dataform 代码库的根目录 definitions 目录中构建和命名 SQL 工作流文件的最佳实践。definitions 目录的推荐结构反映了 SQL 工作流的各个阶段。您可以采用适合您业务需求的任何结构。
出于以下原因，您可能需要在 definitions 目录中设计 SQL 工作流代码的结构：
- 通过指定工作流的选定部分来改善代码库的协作。
- 改进发生组织更改的 SQL 工作流的可维护性。
- 改进代码库的导航。
- 提高代码库的可伸缩性。
- 最大限度减少团队的管理开销。
definitions 目录的推荐结构
Dataform 代码库中的 definitions 根目录包含用于创建 SQL 工作流元素的代码。您可以将 definitions 目录中的文件整理为反映工作流结构的目录结构。
在开发 SQL 工作流时，您可以声明源表并对其进行转换以创建可用于业务或分析的输出表。
您可以区分 SQL 工作流的三个关键阶段：
- 数据源声明
- 转换源数据
- 转换后的源数据的输出表的定义
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 表。通常，在 Dataform 将 intermediate 表执行到 BigQuery 之后，这些表不会被用于其他用途（例如数据分析）。您可以将 intermediate 表视为支持创建输出表的数据转换逻辑。
我们建议您对所有 intermediate 表进行记录并测试。
有关 outputs 的最佳做法
outputs 子目录包含 SQL 工作流的最后阶段：根据转换的数据创建用于业务目的的输出表。
将您计划在 Dataform 将表执行到 BigQuery 后在其他进程或工具中使用的表存储在 outputs 目录中，例如报告或信息中心。outputs 目录中的表通常从 intermediate 表中查询数据。
按与 outputs 表相关的业务实体（例如营销、订单或分析）对表进行分组。为每个企业实体专门指定一个子目录。
如需在 BigQuery 中单独存储输出表，您可以为输出表配置专用架构。如需了解如何配置表架构，请参阅配置其他表设置。
以下示例展示了包含两个业务实体的 outputs 子目录结构：
definitions/
outputs/
orders/
orders.sqlx
returns.sqlx
sales/
sales.sqlx
revenue.sqlx
marketing/
campaigns.sqlx
命名策略
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