此页面由 Cloud Translation API 翻译。

创建表

本文档介绍了如何在 Dataform 中使用 Dataform 核心定义表。

表定义简介

如需定义表，您需要定义表类型并在 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 工作流中定义的以下对象，而不是对架构和表名称进行硬编码：

所有受支持的表类型的表
数据源声明
将 hasOutput 属性设置为 true 的自定义 SQL 操作

Dataform 使用 ref 函数构建要创建或更新的所有表的依赖项树。

编译后，Dataform 会向 SQL 语句添加 CREATE、REPLACE、INSERT 或 MERGE 等样板语句。

以下代码示例展示了使用 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")}

您还可以手动向 config 块添加表依赖项，以便为 SELECT 语句中的 ref 函数中未引用的表、断言、数据源声明或自定义 SQL 操作添加依赖项。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 页面
如需打开代码库，请点击代码库名称。
如需打开开发工作区，请点击相应工作区名称。
在文件窗格中，点击 definitions/ 旁边的更多菜单。
点击创建文件。
在 Add a file path 字段中，在 definitions/ 后面输入文件名称，后跟 .sqlx。例如 definitions/my-table.sqlx。

文件名只能包含数字、字母、连字符和下划线。
点击创建文件。

定义表类型

如需创建新的表类型定义，请按以下步骤操作：

在开发工作区中的 Files 窗格中，展开 definitions/ 目录。
选择要修改的表定义 SQLX 文件。
在文件中输入以下代码段：
```
config { type: "TABLE_TYPE" }
```
将 TABLE_TYPE 替换为以下表格类型之一：
- table
- incremental
- view
可选：如需定义具体化视图，请按以下格式在 type: "view" 下输入 materialized 属性：
```
config {
  type: "view",
  materialized: true
}
```
如需了解详情，请参阅 ITableConfig Dataform 核心参考文档。
可选：点击格式。

定义表结构和依赖项

如需编写表定义 SELECT 语句并定义表结构和依赖项，请按以下步骤操作：

在开发工作区中的 Files 窗格中，展开 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 语句中未引用但需要在当前表之前执行的表依赖项，请按以下步骤操作：

在开发工作区中的 Files 窗格中，展开 definitions/ 目录。
选择要修改的表定义 SQLX 文件。
在表格的 config 代码块中，输入以下代码段：
```
dependencies: [ "DEPENDENCY_TABLE", ]
```
将 DEPENDENCY_TABLE 替换为您要添加为依赖项的表的文件名。您可以输入多个文件名。
可选：点击格式。

以下代码示例展示了将两个表添加为表定义文件的 config 块的手动表依赖项：

config { dependencies: [ "some_table", "some_other_table" ] }

后续步骤

如需了解如何配置增量表，请参阅配置增量表。
如需了解如何配置表分区和集群，请参阅创建表分区和集群。
如需了解如何向表格添加文档，请参阅添加表格文档。
如需了解如何使用断言测试表数据，请参阅使用断言测试表。
如需了解如何使用 JavaScript 定义表，请参阅使用 JavaScript 创建 Dataform 工作流。
如需了解如何配置其他表格设置，请参阅配置其他表格设置。

创建表