创建表

本文档介绍如何在 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 页面。

转到 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 工作流。
如需了解如何配置其他表设置，请参阅配置其他表设置。

创建表