本文档介绍如何在 Dataform 中使用 Dataform Core 定义表。
关于表定义
如需定义表,请定义表类型并在 type: "table"
SQLX 文件中编写 SELECT
语句。然后,Dataform 会将您的 Dataform 核心代码编译为 SQL,执行 SQL 代码,并在 BigQuery 中创建定义的表。
在 Dataform 核心 SELECT
语句中,您可以定义表结构并引用 SQL 工作流的其他对象。
除了在 type: "table"
SLQX 文件中定义表之外,您还可以通过在 type: "operations"
SQLX 文件中定义自定义 SQL 查询来创建空表。如需了解详情,请参阅创建空表。
通过 ref
引用依赖项
如需在 SELECT
语句中引用 SQL 工作流对象并自动将其添加为依赖项,请使用 ref
函数。Dataform 会先执行各种依赖项,然后再执行依赖于这些依赖项的表,以确保流水线排序正确。
ref
函数是 Dataform 核心内置函数,对 Dataform 中的依赖项管理至关重要。借助 ref
函数,您可以引用并自动依赖于 Dataform SQL 工作流中定义的以下对象,而不是对架构和表名称进行硬编码:
- 所有受支持的表类型的表
- 数据源声明
- 自定义 SQL 操作,将
hasOutput
属性设置为true
Dataform 使用 ref
函数构建要创建或更新的所有表的依赖关系树。
编译后,Dataform 会将 CREATE
、REPLACE
、INSERT
或 MERGE
等样板语句添加到 SQL 语句中。
以下代码示例展示了使用 ref
函数的表定义:
config { type: "table" }
SELECT
order_date AS date,
order_id AS order_id,
order_status AS order_status,
SUM(item_count) AS item_count,
SUM(amount) AS revenue
FROM ${ref("store_clean")}
GROUP BY 1, 2
在 ref
函数中,您需要提供要依赖的表或数据源声明的名称。这通常是在其中定义了表或数据源声明的 SQLX 文件的文件名。
如果表名称被替换,请在 ref
函数中使用被替换的名称。
例如,引用 config { name: "overridden_name" }
为 ref("overridden_name")
的表。如需详细了解如何覆盖表名称,请参阅配置其他表设置。
如果不同架构中有多个同名表,您可以通过向 ref
函数提供两个参数(架构名称和表名称)来引用特定表。
以下代码示例展示了包含两个参数的 ref
函数,该函数用于在特定架构中指定表:
config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}
对于未在 SELECT
语句的 ref
函数中引用的表、断言、数据源声明或自定义 SQL 操作,您还可以手动将表依赖项添加到 config
代码块中。Dataform 会先执行这些依赖项,然后再执行从属表。
以下代码示例展示了 config
代码块中的表依赖项:
config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...
如需详细了解 SQL 工作流中的依赖项管理,请参阅声明依赖项。
使用 resolve
引用其他表
利用 resolve
函数,您可以在 SELECT
语句(如 ref
函数)中引用表或数据源声明,但不会将引用添加为依赖项。这意味着,使用 resolve
引用的对象不会影响使用 resolve
的表的执行。
如需详细了解内置的 Dataform 核心功能,请参阅 Dataform 核心参考文档。
准备工作
- 在您的代码库中创建并初始化开发工作区。
- 可选:声明数据源。
所需的角色
如需获取定义表所需的权限,请让管理员向您授予工作区的 Dataform Editor (roles/dataform.editor
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。
创建用于表定义的 SQLX 文件
将表定义 SQLX 文件存储在 definitions/
目录中。如需在 definitions/
目录中创建新的 SQLX 文件,请按以下步骤操作:
在 Cloud 控制台中,转到 Dataform 页面。
如需打开代码库,请点击代码库名称。
如需打开开发工作区,请点击工作区名称。
在 Files 窗格的
definitions/
旁边,点击 More 菜单。点击创建文件。
在添加文件路径字段中,输入文件的名称,在
definitions/
后面加上.sqlx
。例如definitions/my-table.sqlx
。文件名只能包含数字、字母、连字符和下划线。
点击创建文件。
定义表类型
如需创建新的表类型定义,请按以下步骤操作:
- 在开发工作区的文件窗格中,展开
definitions/
目录。 - 选择要修改的表定义 SQLX 文件。
在文件中输入以下代码段:
config { type: "TABLE_TYPE" }
将 TABLE_TYPE 替换为以下表类型之一:
table
incremental
view
可选:如需定义具体化视图,请按以下格式在
type: "view"
下输入materialized
属性:config { type: "view", materialized: true }
如需了解详情,请参阅
ITableConfig
Dataform 核心参考文档。可选:点击格式。
定义表结构和依赖项
如需编写表定义 SELECT
语句并定义表结构和依赖项,请按以下步骤操作:
- 在开发工作区的文件窗格中,展开
definitions/
目录。 - 选择要修改的表定义 SQLX 文件。
- 在
config
代码块下方,编写一个SELECT
语句。 - 可选:点击格式。
以下代码示例展示了一个包含 SELECT
语句和 ref
函数的表定义:
config { type: "table" }
SELECT
customers.id AS id,
customers.first_name AS first_name,
customers.last_name AS last_name,
customers.email AS email,
customers.country AS country,
COUNT(orders.id) AS order_count,
SUM(orders.amount) AS total_spent
FROM
dataform-samples.dataform_sample.crm_customers AS customers
LEFT JOIN ${ref('order_stats')} orders
ON customers.id = orders.customer_id
WHERE
customers.id IS NOT NULL
AND customers.first_name <> 'Internal account'
AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')
GROUP BY 1, 2, 3, 4, 5
手动添加表依赖项
如需添加 SELECT
语句中未引用但需要在当前表之前执行的表依赖项,请按以下步骤操作:
- 在开发工作区的文件窗格中,展开
definitions/
目录。 - 选择要修改的表定义 SQLX 文件。
在表的
config
代码块中,输入以下代码段:dependencies: [ "DEPENDENCY_TABLE", ]
将 DEPENDENCY_TABLE 替换为您要作为依赖项添加的表的文件名。您可以输入多个文件名。
可选:点击格式。
以下代码示例显示了作为手动表依赖项添加到表定义文件的 config
块中的两个表:
config { dependencies: [ "some_table", "some_other_table" ] }
后续步骤
- 如需了解如何配置增量表,请参阅配置增量表。
- 如需了解如何配置表分区和集群,请参阅创建表分区和集群。
- 如需了解如何向表添加文档,请参阅添加表文档。
- 如需了解如何使用断言测试表数据,请参阅使用断言测试表。
- 如需了解如何使用 JavaScript 定义表,请参阅使用 JavaScript 创建 SQL 工作流。
- 如需了解如何配置其他表设置,请参阅配置其他表设置。